Sponsored Link •
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:
P.S. No obscene links, please. People read artima through corporate firewalls.
|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.|