The Artima Developer Community
Sponsored Link

Biotechnology and Bioinformatics Open Source Software
Software Documentation Is Like Weather and Pornography
by Mark Johnson
February 19, 2004
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:

Mark Johnson

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.

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 ( 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,, and, and is a member of the National Association of Science Writers.

This weblog entry is Copyright © 2004 Mark Johnson. All rights reserved.

Sponsored Links


Copyright © 1996-2019 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use