Summary
What is good software documentation? What do you use? What categories exist? What tools do you use? What sounds useful but isn't? What would you most like to see? Stop complaining and start writing.

Software developer documentation is like weather: everybody talks about it, but nobody does anything about it. But even when they try, the result is often basically useless. Why?

I'm currently working at the National Center for Biotechnology Information, designing and writing developer documentation for a gigantic open-source C++ toolkit (3500 classes, 20,000 methods, including privates) and for applications written using the toolkit. The toolkit is available as a source tarball, and we're using doxygen to create the API documentation from comment markup. (Doxygen is like javadoc for C++, minus doclets. I'm working on creating doclets for C++, using doxygen plus Python as the scripting language. Would anyone be interested in using the result?)

Here comes another simile. Good software documentation is like pornography: it's hard to define, but I know it when I see it. I'm after what makes documentation actually useful to working programmers. I'm specifically focusing here on documentation for APIs of very large libraries.

I can think of three broad categories of developer docs: tutorials (for example, Sun's Java tutorials), API docs (javadoc) and cookbooks (O'Reilly Nutshell series). The first hand-hold, the second are a reference for those who already "get" the big picture, and the third provide a local view plus a little crib note to get you started.

What I'd like to know is:

• What makes documentation work?
• What is agile documentation development?
• What are the best examples of documentation you know of? Tools?
• When do you use API documentation? When do you use cookbooks?
• Other than tutorials, API docs and cookbooks, what else is useful?
• What doesn't work?
• Have you read anything good on documentation information design?
• What behavior would you want from a customizable API documentation interface?
• What would you do if you had a very small team (just you, say) to document 3500 classes?
• Please include pointers to documentation that actually is like pornography. Dis I gotta see.

P.S. No obscene links, please. People read artima through corporate firewalls.

Talk Back!

Have an opinion? Readers have already posted 15 comments about this weblog entry. Why not add yours?

RSS Feed

If you'd like to be notified whenever Mark Johnson adds a new entry to his weblog, subscribe to his RSS feed.

Digg | del.icio.us | Reddit

About the Blogger

Mark Johnson is a software developer, trainer, writer, and speaker living in Silver Spring, MD. He works at the National Center for Biotechnology Information, writing documentation and tools for open-source bioinformatics software. He is also president of Elucify Technical Communications (www.elucify.com). He has published dozens of articles on Java component technology, enterprise software development, and XML, and is co-author of the book "Designing Enterprise Applications for the J2EE Platform, Second Edition" (Addison-Wesley 2002). He is currently the author of the monthly Enterprise Java Tech Tips newsletter for Sun Microsystems. Mark has been interviewed on CNN, ITworld.com, and JavaWorld.com, and is a member of the National Association of Science Writers.