Boy Scouts have a saying: leave no trace. One of its basic principles is that when you pack up your camp site, make sure you clean up all the trash. The place should look even better than when you found it.
It’s not a bad principle to keep in mind when leaving a job, either. Projects should be in a good state. I’ve fallen short in one key aspect of this — a conspicuous lack of unit tests in my web apps — but I’ve been more successful in other areas, like up to date versions of Rails and pretty comprehensive documentation.
Documentation is also an easy thing to improve at the last minute. Today I’m reviewing some API docs from top to bottom again, making sure that the confusing edge cases for how an app works are well covered. For my job at VitalSource, this means editing in Confluence.
The apps in Atlassian’s main suite that I’m familiar with — Confluence, Jira, and HipChat — have improved in small increments over the years. I makes sense that they would move fairly slowly; the apps are heavily used in larger companies, so a major redesign or feature change would not be well-received by many of their customers. Of those 3 apps, HipChat seems easily the best designed, and I expect having Slack as a competitor will keep them focused and driven to improve the app.
This post isn’t meant as a rant against Confluence, but as I use it’s default markup language or WYSIWYG editor I’m reminded of just how much I enjoy writing in Markdown instead. For my own apps, I’ve experimented with writing documentation in Markdown hosted on GitHub, which gives me easy publishing and version history. Tweet Marker, for example, pulls a Markdown file from GitHub directly and formats it inside its own web interface for Twitter app developers.
As usual, open formats like simple text files are a great choice for any writing that you want to last. For my new microblogging project, I need to repurpose a lot of writing I’ve done on this blog and move it into more formal documentation. I’ll probably use Markdown and GitHub for that as well.
