Skip to main content

Best Documentation of a Free Software Package

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.

  1. 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+

  2. 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

  3. 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

  4. 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-

  5. 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-

  6. 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+

  7. 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

  8. 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?

Comments

  1. 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

Post a Comment

Popular posts from this blog

Software Design Principles - SOLID

The SOLID software design principles weren't called SOLID while I was in grad school, but the concepts were there in my Object Oriented Design course. They're worth mentioning here, primarily because I think once you start coding and become dangerous, it's one of the best ways to stay organized once you incorporate it into your daily coding routines, and it even changes your way of thinking for the better: https://en.wikipedia.org/wiki/SOLID

Matlab and MySQL

I had a lot of data in a MySQL database that I wanted to analyze. I had a copy of Matlab, so I figured the best way to look at this all would be to plot this data and use some GUI elements to go through various combinations. After some Googling, I found this database connector that seemed to do the trick. I downloaded the files, configured mex to use MSVC 2008, built the connector, then I was able to successfully connect over the network! I ran into two problems, though: The connector does not support fetching columns of type TIMESTAMP, and With the magnitude of data (about 180k rows), access times were really slow. I was able to solve problem #1 by changing my columns to DATETIME, which was supported. I'm still trying to figure out problem #2. It may come down to importing all the data directly into Matlab.