Skip to content

Opinions on Writing Documentation

I’ve been writing a lot of documentation recently; I know I’ve gotten more opinionated about the topic.

Documentation is not one size fits all
Ideally all the documentation should be great, but it needs to be most relevant for the target audience. Developers get irritated by missing details that, if included, would bore management or consumers. Find out or decide who the target should be and try to make them happy. I may have it a bit easy in this regard for my day job – we’ve got a technical documentation group that takes our specifications and technical documentation and re-targets them for the user and programmer’s manuals.

It starts with the specification
I spend a lot of time getting the specification as complete as possible, and I spend more time keeping it up to date. Where I work, it is a necessity since we contract out some of the development. If it isn’t in the spec, it probably won’t get delivered. Beyond that, the spec help defines the narrative of the documentation and provides a lot of the material for future documentation.

When possible, write obvious code, not obvious comments
Don’t waste your time or energy writing comments for very blatant sections of code. Save that effort for the hard, quirky, or complex stuff.

Automated tools can cause crappy documentation
I’ve used automated tools like Doxygen or SandCastle to generate documentation for a few projects. They produce good looking documentation, but I don’t like them for two reasons: they are fiddly and they give you a false sense of accomplishment. You can waste a lot of time trying to get ‘perfect’ looking documentation when you should be actually documenting things. After you finally get things set up, the documentation can look spectacular — but it is just a gilded frame. When I’m in the middle of coding things, I like to write quick comments. I don’t want to stop so I can look up proper comment syntax. This may just be where I work – we don’t produce a lot of this type of documentation so I’ve never really learned one of the systems. I’ve seen very well done automated documentation, but you really need to buy into the system to make it work well.

Tagged , ,

Chocolate IPA Brew Notes

This brew was another experiment; I wanted to try something new.

  • 1 lb. Muntons Chocolate Malt
  • 6.6 lbs Briess Sparkling Amber LME
  • 1 oz. Cascade Pellet Hops at 60 Minutes
  • 1 oz. Cascade Pellet Hops at 20 Minutes
  • 1 oz. Cascade Pellet Hops at 3 Minutes
  • 1 Smack Pack of Wyeast American Ale yeast

My brewing procedure was pretty straightforward. I steeped the Chocolate Malt for 18 minutes as I brought three gallons of water to a boil. It was removed right before I reached a rolling boil. I then added half the Amber LME. When I reached a rolling boil again, I added the first hop addition and started the 60 minute timer. At 20 minutes, I added the other half of the Amber LME and the second ounce of hops. Just before pulling the kettle off the heat (T minus 3 minutes) I added the last ounce of Cascade. I cooled the wort in an icebath, aerated, and added the yeast. The O.G. for the beer was 1.052.

Tagged , ,

Scotch Barrel Scottish 70 Shilling Recipe and Notes

I had the hankering to brew again, and I wanted to try something different.

I’ve been interested in brewing a Scottish 70/- or 80/- for a while. It sounded similar to the English bitters I like, but different enough to branch out a bit. There is one more wrinkle I threw in there – I had some friends wanting me to try to make something like a Kentucky Bourbon Barrel Ale so I figured I’d combine the two experiments. Here’s what I’ve got:

  • 1 lb. Simpsons Caramalt
  • 3.3 lbs Muntons Amber LME
  • 3.3 lbs Muntons Dark LME
  • 1 oz. (U.K. Grown) Fuggle Pellet Hops at 60 Minutes
  • 1 vial White Labs 007 Dry English Ale yeast
  • 1 tsp. Irish Moss


  • 1.5 cups Clan MacGregor Scotch Whisky
  • 1.5 oz. Hungarian medium toast oak cubes

A few days before the brew day, I put the boiled the oak cubes for a few minutes in water. Then I drained the water off and dropped them in a mason jar with the Scotch. According to my (relatively anemic) research, I wanted to have the oak in Scotch for about 2 weeks. When primary fermentation ends I’ll rack the beer into secondary on top of the Scotch and oak.

My brewing procedure was more involved than usual, but still pretty straightforward. I steeped the Caramalt for 18 minutes as I brought two and a half gallons of water to a boil. It was removed right before I reached a rolling boil. I then added the Amber LME and the Fuggle hops, and started the 60 minute timer. At 20 minutes, I added the Dark LME. The Irish Moss was thrown in at 15 minutes. The O.G. for the beer was 1.052.

Tagged , ,

The Apps I Use On The LG Optimus V: Music and Media

It’s been a month and a half since I first rooted my Optimus V. As I’ve gotten more comfortable with the device, the software I use daily has changed a bit, so I figured I would run through my current set up.

First, I’ve stopped using nearly all of the optimization software I installed shortly rooting the device. No more ATK, CacheMate, CPU Tuner, etc – I don’t see a noticeable performance or battery difference with them enabled, so I disabled them. The way I see it, the fewer fiddly software bits necessary, the better. The original reason I installed this software was to try to increase the terrible battery life of the phone. Nearly all the problems I was having with the battery were due to the battery quirk I mentioned previously.

The software I wanted to mention today is more standard fare – it’s the stuff I use on a daily basis.
Music and Podcasts
One of the main reasons I switched from the LG300 I used to use was to stop carrying around my sim-less iPhone as a media player. I work in a cubefarm, and I usually need the music or podcasts to drown out the ambient noise. My ‘workflow’ for media consists of three applications:

  • MyPod – The UI is in dire need of a once over by a user interaction designer, but MyPod is a very full-featured podcast downloader. This is actually the first application I bought from the Android Market.
  • WinAmp – I’m excited to see that this product lives on. I loved WinAmp on my PC back in college (almost a decade ago!) and Nullsoft still makes a decent media player. The primary reason I use WinAmp over the default media player is their lockscreen player controls. These are vital in a work environment with numerous interruptions.
  • Amazon MP3 – Until Amazon unveiled their Cloud Music Player this app was languishing unused on my phone. Now, it’s basically my stand-in for iTunes. I’ve been slowly uploading my music collection from my Mac to my Cloud Drive and using the Amazon MP3 app to download albums I want to listen to directly to my device.

It’s strange how liberating it feels to not have to (micro)manage iTunes to get the media I want on my phone.

Tagged , ,

Optimus V Battery Drain Quirk

I’m still getting used to my Optimus, but I must say that the experience has been mostly positive. Since getting the phone, I’ve been plagued by an occasional extremely short battery life – like five hours to go from a full charge, to a dead battery. I though I had the problem cleared up after I rooted it , but the next day it re-appeared.

Turns out that this is a fairly common issue with several Android devices. If you are experiencing a shorter than expected battery life check the Battery Use of the Cell Standby Component (Settings/About Phone/Battery Use/Cell Standby) if it reads 50%, then you’ve got the bug. To fix it, put your device into Airplane mode (via the power button), and then immediately take it out of that mode. This blog describes a much longer process that I found unnecessary. If I do this whenever I restart the device, it does not exhibit this issue.

Tagged , , ,