Re: Technical Writers Needed for API Doc: Really?

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

Cedric Simard wrote:
> 
> Hi all,
> 
> I'm looking for resources (an article, a particular messsage in a forum, a
> page on web site...) that talk about the added-value of technical writers
> when it comes to documenting an API.
> 
> All CTOs and most of the programmers I've met till now keep on saying that
> only a programmer can produce documentation for programmers. ...

I'd suggest reading Fred Brooks' "The Mythical Man Month".
http://www.robelle.com/library/smugbook/manmonth.html

This is the classic (1970s but still in print) book on the problems of
large software projects. Brooks ran one of the first really big ones,
IBM's OS 360, and learned some hard lessons. When he wrote about them,
much of what he said was revolutionary. It still reads well today.

I'd say anyone involved in either software development or any type of 
project management should read it.

He discusses documentation in some detail, suggesting things along the
general lines of (my interpretation, and it's several years since I
last re-read the book):

Getting  things like the spec right is the senior wizard's prime 
responsibility. Most of the manager's responsibilities are also
tied to documents -- schedules, plans, ...

In fact, consider forbidding the senior wizard to write any code.
Just have him write a spec clear enough the rest of the team can 
implement it. If they can't, he can give them hints and then
rewrite the spec. This gives a gain in overall team productivity
and improves the product; one architect controls the design and
the spec is clear.

Instead of making the tech writer the last person hired, late in
the project, make him or her the second, right after the wizard.

Some docs -- including the user manual for a software tool, which
should be closely related to the spec -- must be written by the
wizard, the only person wth a full understanding of the design.
The tech writer is the editor, adding references and examples,
asking the wizard to clarify, ...

I've never seen a team that actually ran like that. If anyone
knows of any, please tell me where to send the resume :-)

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
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.