Re: Quality of source material from Development

[Sandy Harris <sandy -at- storm -dot- ca>]

Salan Sinclair wrote:
> 
> How much written information should software development department provide
> for a technical writing department?
> Option 1. Enough for tech writers to write the documentation, with few
> questions.
> Option 2. Enough for tech writers to get a complete scope but not the
> details.
> Option 3. Enough for tech writers to get started, or whatever information
> developers can provide in the time allowed.
> 
> A friend of mine is a Doc Manager at a new company. She expected Option 1,
> but the Dev Manager is delivering Option 3.
> 
> The documentation is for command-line interfaces for new networking
> software. (The question could apply to any software, but sometimes GUI
> software is easier to write by simply working with the product.)

A division I've seen work well in several projects is that programmers
write Unix man pages (or the equivalent on other systems), terse highly
technical reference material. I then write other things -- documentation
for end users, tutorial material for developers using the API, design
rationale docs to help sell the product, procedural info for system
administrators, ... -- whatever else is needed.

One very handy side effect of this is that I can use the version control
system to track changes to the man pages. This means I learn of most
software changes that affect my docs, without having to rely on
developers remembering to email me about them. 

This requires that the programmers be literate and that their management
include documenting the code as part of their requirements. Neither of
those is always the case, but in my experience both often are.

My current project is one example of this. It's also networking software
with a command line interface. All of the docs are on the web.

My stuff:
http://www.freeswan.org/doc.html
The man pages:
http://www.freeswan.org/freeswan_trees/freeswan-1.91/doc/manpages.html 

On this one, the programmers are definitely literate. In an 8-person
team we've got two O'Reilly authors and at least three post-grad degrees.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collect Royalties, Not Rejection Letters! Tell us your rejection story when you 
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of 
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.