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

AWS Development On A Budget

I was interested in hosting a small portfolio of applications in AWS, but I wanted to keep costs down.  I was willing to maybe host about $30-$40 a month of servers just to showcase some of the applications I was putting together.  Here's what I came up with. The basic capabilities here were: serve up about 6-10 applications that would require some level of web application hosting, database, file storage for larger items, and possibly queuing or email schedule jobs to run periodically to either scrape websites for new data or access APIs regularly These were the services in mind, all out of US-East-1 (Virginia): EC2 instances are pretty cheap.  You can run a t3a.nano for about $3.38 a month, or a t3a.micro for about double that for $6.77.  The more things can run on one of these instances, the better. Lambdas also don't really add up to much if they are scheduled jobs that do not consume large amounts of memory or computing.   The cost of a Lambda run as part of an API gateway

The TL;DR guide to git

While in the past I've held a pretty high opinion to using mercurial for version control, the majority of version control these days seems to done in git.  Here were the commands I found most useful to get productive with git right away. # Clone a repository from an origin, i.e. my github MaskingUtils repository git clone git@github.com:caelumvox/masking-utils.git # Add a file after it's been updated to stage it for commit, or add a new file git add filename # Commit the file to local repo git commit # Push the file to the origin so the rest of the team can see it git push # List all locally tracked branches git branch git branch --list # Get a list of all branches from the remote git branch -r # Create branch locally git branch develop # Push the branch to the origin repository to make sure it is tracked there git push --set-upstream origin develop # Pulls latest from all local branches tracked from origin; won't pull non-tracked branches git pull --all # Fetch the branch