One oft overlooked artifact in software development is the documentation. An API that is not well documented is no API at all when time is of the essence. That's why I think it is important to discuss some of the tools I have used and their documentation.
What are your thoughts? Can you think of some excellent examples of documentation for free software?
- AutoIt - I love how you simply press F1 within the AutoIt editor and boom, the reference to the particular syntax or function pops up in the help window. This help file is well written, self-contained, and chock full of examples that can be opened up in the editor right from the help, a fantastic symbiotic relationship. After installing AutoIt and giving it a try using their examples, I was able to create client/server scripts, GUI scripts, and window management scripts in no time. Overall, AutoIt is tops in this competition. A+
- MySQL - At the bottom of each page of documentation that discusses a particular statement, users are able to post comments containing code snippets for that particular statement. This is great... MySQL provides a bare-essentials printout of the supported SQL statements, and they rely on the seasoned developers to do this rest! Microsoft does this as well for their pages, and I think this is great because it puts the burden on the community to come up with good coding examples. A
- C++ (www.cplusplus.com) - Though I have never used the forums or articles, the references on this site regarding the generic parts of C++ are excellent. Less is more. Neatly organized, I go here first even if I am working with MSVC EE 2008. A
- Java - The tree-like structure of the code as it is organized by package, class, and method is also a fantastic resource. What I like here is that it is easy to find adjacent pages if I happen to want to look at something similar (like Integer versus Float and what they each have to offer). I wonder why Google still chooses to display the 1.4.2 version of each searched Java library? A-
- Perl (perl.org) - Loads of documentation on the website and lots of decent examples. I do wish their explanation of references was a little more straightforward. Is the little nickname they give to each of their categories (perlop, perlfunc) of any help to anybody? I find it more of a distraction than anything else. B-
- MSVC C++ - It used to be a lot worse, but Microsoft has taken a step forward in reorganizing their content and making it a lot easier to find certain terms. I particularly like the ability to select between different versions of the C++ compiler and libraries by simply selecting the drop down on each page, and I also like some of the blog posts. However, the ease of navigability depends on the mood I am in. If my brain is not in a MS mood, it becomes very hard to navigate to a particular library, and many times I am at the mercy of the search feature. C+
- Boost - Very well documented with good organization, but the readability varies from one library to another, particularly because nearly every library is written by a different person. Some libraries are easily understood (Like DateTime and lexical_cast) and some practically require a PhD (see the String Predicates or Macros). C
- ACE+TAO - Save for some brief examples, it is practically non-existent. Relying on Doxygen to provide your users documentation when the code hardly has any Doxygen statements does not help one bit. I might as well go through the source code directories myself. F
What are your thoughts? Can you think of some excellent examples of documentation for free software?
Leaving TAO aside, there are 3 books in print about ACE. I co-authored them so am not quite unbiased, but they do go quite a bit past the doxygen-generated docs. I do agree with you, though, that the doxygen-generated docs could use some improvement. Want to help? ;-)
ReplyDelete