Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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

share|improve this question

closed as not a real question by Walter, Yusubov, gnat, Robert Harvey, Yannis Rizos Nov 5 '12 at 23:22

It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center.If this question can be reworded to fit the rules in the help center, please edit the question.

2 Answers 2

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").
share|improve this answer

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.

share|improve this answer
    
Thanks for the inside on the subject. I am actually worried about how to reference certain things? e.g; images from other documentation especially when your documentation/manual will also be found on WWW. I have given the job to write a cookbook/training manual on IOS for new developers joining my company and I am worried if its possible to just copy and paste the images from a copy righted documentation of apple with reference? In other words I wanted to know how to reference images you copy? –  itsaboutcode Dec 20 '10 at 11:55

Not the answer you're looking for? Browse other questions tagged or ask your own question.