- Spotify-like on-demand streaming music.
- Video, too?
(For the archives: the particular announcement tease.)
Drawn to Learning
Two great tastes that go great together: RSAnimate and Ken Robinson.
Doc Robot
An old saying has it that documentation is like sex: even when it’s bad, it’s still pretty good. I’d like to amend this with a more applicable conclusion: if what you offer me is similar to what I can generate myself, it’s probably pretty bad.
A reader recently whined about the documentation of some open source projects. Something that’s prevalent in open source projects is the impulse to just run your codebase through Javadoc or Doxygen, upload it to docs/ and call it a day. Often, there won’t even be any documentation added to the methods. Sometimes, the property getters and setters and maybe methods will be stubbed out from their names. (There are tools for this, which is semi-sickening in the way they’re being abused.) That’s not documentation, that’s running a tool for someone. You’re not informing, you’re speculatively caching.
Rather than spending those five minutes setting up a shell script to run any of those infernal machines, type out some actual documentation. Say “if you want to use this component, look at X, Y and Z and work your way out”. Point to a sample project. Actually document the five or so instrumental methods or entry points. Highlight what you’re not satisfied with so that you invite patches.
I’m a big fan of projects having automatically generated documentation, but only in the sense that there’s a machine that’s so well oiled that people document freely and just need to run a script to regenerate everything, and that the process invites writing or refining documentation. Most generated documentation in actual use just provide links and class diagrams; nothing that people interested in those things can’t generate by themselves. If they are really interested, they probably have separate, better tools to provide that for them.
You don’t have to be an awesome writer to clarify and help people understand your code. Neither style nor length need play any part. The first 300 words are the most important, and you don’t even need to go that long to spec out the red threads. (This post is longer than 300 words.) You do have to resist the temptation of the tool filling the folder with a cross-referenced class index, and maybe someone who’s just judging your project by the file count will blame you for not keeping those files, no matter how silently worthless they are. The people you’re trying to get to work for and with you on your project will be all the more rewarding for your effort.