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.
Advertisement
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.
Mark Johnson
P.S. No obscene links, please. People read artima through corporate firewalls.
What makes documentation work? 1. Be reachable 2. Be searchable 3. Be of good quality (reachability and searchability may be bth viewed as quality measures; here I'm referring to quality of content and form).
The most important thing about documentation is that it is correct, to achieve that it must be maintainable with minimal effort (we're a lazy bunch really). I think that is why javadoc is so wonderful. The documentation is right in the programmer's face. Its hard not to maintain it. Add a code review process that puts as much emphasis on the doc comments as the code and you're mostly there.
javadoc does your 2nd category (reference) really well, but I think it could go further down the category 1 and 3 (overview and cookbook) tracks.
I have been thinking about that lately, and I think we would benefit from marking things as "fundamental". By fundamental I mean they would appear somewhere in minimalist sample code for their container (package or class).
I would mark the main classes in a package as fundamental. I would also mark the simplest constructor, or factory method for all classes. Some classes might have hundreds of methods but the core ones would be marked as fundamental.
The documentation should put the fundamental stuff near the top.
Have you noticed how hard it is to take the first bite out of a really huge apple, but after that its easy?
We need a way to make that first bite easy when reading API documentation.
There's a fourth kind of document that is not usually created, but is very helpful. I'm not sure of the right term -- something to turn a user into a developer. The tutorial gets you working, and the cookbook gets you doing useful stuff, but they don't help you understand the library. Instead developers are usually forced to infer everything from the reference manual.
A code map is one way of doing this. I like chronological maps -- when you do some typical task, what's the call chain like? A map that takes you into the deepest part of the system. All too often we end up seeing that deep inard, because of an error in our code or someone else's. Or we want to change that inard, or we want to understand it so we can fit our mind around the library and how it should work. This is true even for small libraries, but for something large (and especially something framework-like) it's really important. And seldom actually written.
I also like to see suggestions in documentation. Warnings about mistakes, pointers to other places, etc. For instance, if there's a method that seems like it should do something, but doesn't, direct the person to the method you think they will want.
I agree that searchability is a big deal. In fact, I'm thinking about how to design a search language for C++ source code. Currently, I'm thinking about designing an XSD schema that can represent the program metadata and class structure, and then using XPath expressions to query the source code. I do think that "grep the documentation" is only a tiny bit smarter than "grep the source". Maybe what we need is some way of navigating the class structure that's cleaner than a huge tree widget. Maybe there's a way to use treemaps (http://www.cs.umd.edu/hcil/treemap-history/index.shtml) to browse easily through a class hierarchy. Has anyone ever seen anything like this?
The comment about "quality" makes sense, but I think what you're calling quality is a necessary-but-not-sufficient condition for, well, quality. My original question is, essentially, what is quality in software documentation? What is good information design for API docs, for example? Javadoc's good, but what's better, meaning, what's more useful?
Nowadays, much of the documentation I used is mixed into the IDE. For example, I often type in "someObject." and wait for the dropdown list of methods to appear, rather than look them up. Some IDEs even show a summary of each method in the list as you highlight it. In many cases this is sufficient.
Well, really documentation is distributed: between the IDE, the context-sensitive (or not) documentation, Google and newsgroups.
In the more complex cases, where you really need to read something meaty about a class or method, a lengthy treatise without any code samples can be really aggravating.
Library documetation must be well optimized like the code itself. Of course it must be complete and precise, but people often think completeness is verbosity. It's not.
Bad example:
string::isEmpty() Synopsis: Checks whether the string object is empty. Return value: true if the string is empty (contains no characters), or false otherwise.
Better example:
string::isEmpty() returns true if the string object is empty.
Now compare the time you spent reading these two examples.
Doxygen: it just sucks. It makes people think they can get out of writing documentation for their code. As a result, most of the libraries with doxygenic documentation are almost useless.
I get a little confused by the statement "the string object is empty" because I distinguish between an empty string and an empty object.
It seems like for a few very common and self-evident methods, like isEmpty(), no documentation is needed and when present only serves to muddy the waters.
> I get a little confused by the statement "the string > object is empty" because I distinguish between an empty > string and an empty object. > This seems reasonable.
> It seems like for a few very common and self-evident > methods, like isEmpty(), no documentation is needed > and when present only serves to muddy the waters.
Well, if you distinguish between an empty string and an empty object then presumably you want to have a polymorphic isEmpty() that can be applied to both strings and other objects?
Or would you rather have isEmptyString() and isEmptyObject(), and have each of them throw exceptions when htey aren't called with the right type of object. Or would such code be trapped at compile time by a static checking system?
I think you set a trap for yourself by assuming that some concepts are axiomatic. You are preselecting for a particular audience, which may or may not be a good thing, depending on how accurate your audience preconceptions turn out to be. One man's "obvious" is another's "what the hell are they talking about", and documentation is supposed to answer questions, not raise them.
The previous remarks about automated doucmentation do remind me that sometimes humans produce similar nonsense. Microsoft and other vendors would frequently produce manuals in which the documentation for a menu selection would read something like:
"Dweeb -> Fnoogle: You select the Dweeb -> Fnoogle menu item when you want to Fnoogle the currently selected Dweeb. If no Dweeb is selected then the menu item will be inactive" which, while accurate, was little use if you didn't know what a Dweeb was or what Fnoogling involved, and pretty much no use at all if you did. But, by dint of adding hundreds of such items the documentation team presumably grew the manual to the requisite length.
Documentation should help. If it can't do that then it should at least not hinder by focusing the reader on useless verbiage.
Posts: 2
Nickname: yamir
Registered: Feb, 2004
Re: Software Documentation Is Like Weather and Pornography
> It's not clear to me what "reachable" means. > > I agree that searchability is a big deal. In fact, I'm > thinking about how to design a search language for C++ > source code. Currently, I'm thinking about designing an > XSD schema that can represent the program metadata and > class structure, and then using XPath expressions to query > the source code. > I do think that "grep the documentation" is only a tiny > bit smarter than "grep the source". Maybe what we need is > some way of navigating the class structure that's cleaner > than a huge tree widget. Maybe there's a way to use > treemaps > (http://www.cs.umd.edu/hcil/treemap-history/index.shtml) > to browse easily through a class hierarchy. Has anyone > ever seen anything like this? > > The comment about "quality" makes sense, but I think what > you're calling quality is a necessary-but-not-sufficient > condition for, well, quality. My original question is, > essentially, what is quality in software > documentation? What is good information design for API > docs, for example? Javadoc's good, but what's better, > meaning, what's more useful?
I don't think what treemaps or any other graphical solutions are appropriate.
For me as a developer, most natural documentation is well commented source code, formatted accordingly my favour.
So it should looks as rich text document with lots of view options above structured representation.
> The most important thing about documentation is that it is > correct,
Although this seems obvious, I have often found that differences between the code comments and the code itself to be a useful indicator of where to start looking for problems. In that way, bad comments can act a bit like a warning light.
Ideally, what we want is code that documents itself (and by that I don't mean code that is readable - a rare enough luxury in itself) but code that can be parsed into plain English (or any other 'real' language). After all, code is basically a representation of a plain English specification in the first place.
> Doxygen: it just sucks. It makes people think they can get > out of writing documentation for their code. As a result, > most of the libraries with doxygenic documentation are > almost useless.
I disagree that doxygen sucks. Well, sort of.
The standard HTML output from doxygen is almost worse than useless. It just got a facelift, but there wasn't any improvement in functionality. But that doesn't mean that embedded documentation is a bad idea. Take javadoc, for example. It isn't perfect, but it's <i>useful</i>, or at least I use and like it, and that's good enough for me.
I think the problem with doclet-type documentation tools like doxygen and javadoc is the lack of imagination in how content is structured. Doxygen gives Huge Lists, or fragments of trees, and sometimes-useful-sometimes-stupid graphs. javadoc is pretty much limited to Java package structure, or Huge List (again).
I think that the problem with doxygen (in particular) is that the interface is unusable. But the underlying data--doclets in comments--could be presented in a more useful way, if it matched programmers' use cases. So I think it's a usability issue with doxygen's presentation, and not a problem with the whole idea of doclets.
I agree with you, documentation of API is a very cryptic and time consuming process and if the library is huge it will take years.
Even though with good tools available the forecasting of completion of the documentation is highly erratic. Thus I agree that it is like weather. We will not know when it will complete or how good it will be.
It is not like pornography though, because it is not that ubiquitious!!!!
I read on some documentation from ecsoftware, these guys make Help and Manual 4. "There is no substitute for hard work". Thus if the Technical Writer wants to give quality he has to put in hardwork even though the developers and managers may have other ideas.
Coming back to Java documentation. For Java documentation there are no good tools available. If there are then I dont know. I would be obliged if someone suggests a good tool which will read from a jar and generate javadoc compatible documentation. I am looking for a tool which can assist in incremental build of the documentation, as the jar changes. Secondly I would like to keep the comments for the java files externally and not as a part of the java files.
For .NET we have a very good tool called Document! X. Recently version 5 was released. It is available for free trial from innovasys.com. It is an excellent tool for .NET API documentation and various other APIs. But alas they do not support Java API documentation.
If anyone out there has any idea about a Java API documentation tool which supports incremental build of the documentation then please let me know.: maheshnvs@yahoo.co.in.
The type of software development setup we have is different. Our developers do not write comments in the source code. It is the duty of the Technical writers to write the documentation.
Moreover if there is not java documentation someone can make it. it will sell heavily.
Thanks for your documentation efforts, i just downloaded your tarbal and will be going through that shortly!
I found your link in going through Google and in trying to find out if DOXYGEN or a similar tool, can read a directory containing C/C++ source code and output a copy of that source code to a new directory, where the copy of the code will contain hyperlinks to key class references ect, throughout the new directory?
Xref-tech has this feature for JAVA code and it's free, and it also this capability for C++, but the C++ version is fairly expensive!
Maybe your tool has this capability? or do you know if DOXYGEN or other has this capability? I looked through some of the DOXYGEN website examples and didn't see any examples of this capability as of yet!
It must be concise. It must be easy to understand. It must have quick start to start programming with the API. It must have a more complete guide showing the API most extensive use. It must show the API changelog. It must make extensive use of JavaDoc. It must evidence in a fairly manner the API new features when a new released is delivered into production.
Flat View: This topic has 15 replies
on 2 pages
[
12
|
»
]
Previous Topic
