Re: Quality of source material from Development

Subject: Re: Quality of source material from Development
From: Sandy Harris <sandy -at- storm -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 11 Dec 2001 11:49:58 -0500

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.



Follow-Ups:

References:
Quality of source material from Development: From: Salan Sinclair

Previous by Author: Re: Screenshots of GUI: copyrighted?
Next by Author: Re: Quality of source material from Development
Previous by Thread: Re: Quality of source material from Development
Next by Thread: Re: Quality of source material from Development


What this post helpful? Share it with friends and colleagues:


Sponsored Ads