Steve Losh's Teach, Don't Tell

141 tabs are open in my browser right now. Lots of them are "I'll read this later" tabs. One of them is Steve's "Teach, Don't Tell" article. It's a good read that explains many of the current trends in writing technical documentation, and why they're horrible. The trends are:

• "Read the Source" Trend
• No real documentation is provided. The source IS the documentation.
• Solely relying on this is bad because: The source is good for an expert of the tool already, but is next to worthless at introducing the tool to a novice.
• "Read the Tests" Trend
• The idea here is that since the tests actually use the tool in question, it should do a good job in providing examples to the user.
• Solely relying on this is bad because: While there are tests that cover normal use cases, many are for edge cases, which should, by definition, happen less than average.
• "Literate Programming" Trend, "Read the Docstrings" Trend, "Read the API Docs" Trend
• These three were covered separately, but the basis of these trends are the same: Documentation is added to the source code (or, the source code itself is made to be more readable). Later, tools can transform this documentation automatically into something that is more accessible than just navigating around source code files.
• Examples include JavaDoc, Doxygen, Docco, Python docstrings, and many more.
• Solely relying on this is bad because: Its a more elegant approach to "Read the Source", though still lacks information such as "what is this?" "Where to begin?" "How to use?" and more. However, these references become invaluable once someone is knowledgeable with the tool.
• "Read the Wiki" Trend
• Documentation can be written by the authors as needed. Typos can be fixed, extra information can be filled in, anything that is lacking in the documentation, can be done by anyone interested.
• Solely relying on this is bad because: It may be better than nothing, but it is more laziness on the part of the developers than anything else, because now it is removes the responsibility of writing good documentation away from the developer, and onto people that are interested in having good documentation. To paraphrase Steve, rather than the teacher asking for feedback on their lesson plan, its as if the teacher is giving the lesson plan to the students instead. Steve really hates these documentation wikis with a passion.
• Personally, if the wiki is done right (sadly, they are rarely done right), I believe it could be good documentation. At that point, the wiki would be less of a wiki and more of a CMS though.

In the end, none of these are BAD, per se, but if all that the user has is the ability to look at the source, and/or the tests, and/or the API docs, and/or lazy-and-unfocused documentation, then the developers have failed to provide documentation that can teach.

What I need to remember is that, it doesn't matter how great something I make is. If other people don't know how to use it, it will languish. Therefore, I should strive to make good documentation that teaches, and this requires effort on my part. I cannot rely on tools to automatically pull this information out for me.

Give Your Java Program a Good Command Line Interface

Let's admit it: in today's world (even yesterday's world for that matter), there hasn't been much demand for starting a Java program from the command line. Pretty much all we do now is use our favorite Java IDE, perhaps run a maven build, everything gets put into a jar, war, ear, or something-ending-in-ar which gets deployed, then the server blows up and you have to undo everything.

Even if a java program doesn't get deployed to a server, we usually just run it right from inside Eclipse, NetBeans, IntelliJ, or what-have-you since its usually to debug something, or is a college programming assignment. So the need to spruce up a Java program to be easily called from the command line just doesn't come up very often. Some may argue this is for the better since java programs have that short start-up delay when kicking up a new jvm instance. I'm not here to argue on that point however.

Let's talk about a specific point of time in your java project's lifecycle, where you decide it is getting too annoying for you or your clients to start up your java program using:

java -jar awesome.jar

You may even be using properties as a cheap-n-easy way to do arguments:

java -jar awesome.jar -DmakeStuffWork=true -Dname="Bob Newhart"
If it is to run on the terminal or in a window, there will come a time when you wish you could just have the program behave like every other executable on the computer. I found myself in this very situation when I was creating lsdup, a command-line tool to list duplicate files. It needed to be able to run elegantly enough that the people using it didn't need to know or care about Java. The only requirement was that the users had an installed Java VM.


I was able to convert from "java -jar lsdup.jar" to just "lsdup.exe" on Windows by wrapping the jar in a different tool which is essentially a very small executable (or even script), called Launch4J. In Linux land, I used bash scripts (which should also work in principle on Mac OS X, though I've not tested it) to convert it to "./lsdup.sh".

For the command-line options, I used Apache Commons CLI to grab all the input.

Of course, this all works with Maven. As always, Stack Overflow has the answer for working with Launch4J targets. You can also run the bash scripts mentioned above in maven as well.

The not-so-obvious part is that while it would have been nice to cross-compile (or cross-wrap, in this case) the build so that I could create the Launch4J Windows exe wrapper in Linux in addition to creating the shell script, or conversely create the shell script in Windows in addition to creating the exe. Laziness got the best of me and I did not figure out how to do it.

What I ended with was a maven script with two profiles: one which builds the shell script when on Linux, and one which builds the Windows exe when on Windows:

  <profiles>
    <profile>
      <id>posix</id>
      <activation>
        <os>
          <family>!Windows</family>
        </os>
      </activation>
      <build>
        <!-- The maven code to execute the shell script (linked above) goes here. -->
      </build>
    </profile>
    <profile>
      <id>windows</id>
      <activation>
        <os>
          <family>Windows</family>
        </os>
      </activation>
      <build>
        <!-- The maven code to wrap Launch4J around the jar (linked above) goes here. -->
      </build>
    </profile>
  </profiles>

This worked well for me, and I will consider it in the future should I ever need to create another Java program to behave like any other executable file.

Fantastic List of Free Programmer Friendly Fonts

I used to be pretty fanatical about which fonts I used a half-a-decade ago, back when I was still doing most of my development on Windows 2000 (!) and the default mono fonts on the system were not ideal for staring at for most of my workday, either on the MS cmd.exe or Eclipse. I had to switch my font or suffer. Fast-forward to today, I do most of my programming on Linux now, and the default mono-fonts that come on Fedora or Ubuntu are decent enough that I don't have a need to switch fonts.

I used to be an Envy Code R man, myself. Now, there's a plethora of different fonts to choose from. There's so many to choose from, it can be hard to decide. Thanks to http://www.slant.co/topics/67/~what-are-the-best-programming-fonts you can easily compare against them to find one that suits you best.

Adobe Source Sans Pro Open Source Font

It's a vector font optimized for user interfaces and coders.

See it at: http://store1.adobe.com/cfusion/store/html/index.cfm?event=displayFontPackage&code=1959
Download it at http://sourceforge.net/adobe/sourcesans/wiki/Home/
Read about it at http://blogs.adobe.com/typblography/2012/08/source-sans-pro.html

It is open source as well, however I was hard pressed to see what the license was, exactly.