API/Technical Writers Guide [closed]

Question

Is there any good book/tutorial/guide for programmers, which can help them to write good programming documentation/tutorials/guides?

Answer 1

My advice is to look at tutorials that you consider good and copy their style.

Some things that generally improve documentation:

1. Be redundant. Repeating yourself with several examples goes against the grain of developers who like to never repeat themselves. But in documentation this is actually very important. It gives the reader more than one chance to get something.
2. Examples. Examples. Examples.
3. Try to put on the hat of a newbie reader every once in a while and see how it reads. You'll often find you're assuming a lot of stuff that the reader doesn't know.
4. Good documentation is usually in an editable/wiki format, so that it can be gradually improved by readers.
5. Humor is a good thing (e.g. Python docs, especially early versions).
6. Write for people, not machines. Programmers tend to be terse in their documentation: *(e.g. "returns null upon failure"). But being just a bit more verbose makes things easier to parse and more readable (e.g. "The function returns NULL if if fails to open the input file").

Answer 2

I've been doing programming docs for about 25 years, from the Unix Programmer's Manual to Microsoft server apps. Technical documentation has a pyramid of priorities:

• Is it technically accurate? This is job #1. Once you introduce something that is not correct, you lose the reader.
• Is it complete? Have you documented all of the args, the return values? Did you document all of the exceptions? Any important gotchas? These typically go into a remarks/comments section. For example, if a method also sets a public property to a value, tell the reader.
• Is it appropriate? Is this information that the developer needs or are you just filling space? Sometimes it is better to refer to a URL where they can learn about some technical information than for you to attempt to paraphrase or restate it incorrectly.

When possible, provide examples. In many cases, a developer will take a decent example and run with it.

Technical docs are written in the reverse order in which they typically appear. You usually write the reference section first, then a guide/cookbook section, then an introduction, and finally a tutorial if you have time.

And don't forget a good editor. Much as a developer should not test and verify his own code, you should not edit your own docs.

Almost all decent-sized companies have a document style guide. I even have an old AP Style Guide text from the university days. Read Strunk and White.

You might even look into some community college courses. Like non-developers who do not code, non-writers have no idea how hard it is to write decent developer documentation. If you've ever stared at code you wrote 3 months ago and cannot figure out what the heck you were thinking, imagine trying to document code from someone who is no longer with the company. It's more challenging than writing the code in the first place.

Be careful about humor. Depending upon your abilities, it can been misunderstood. I don't recommend it. As far as good documentation being found in a forum where anyone can change it, good luck with keeping the spammers out.