Mar 13 2009
Documentation is Hard… but you should still do it
One of the things I struggle with is documentation. Jeff Atwood and Mike Pope both suggest that “if it’s not documented it doesn’t exist ” and I have to agree. Despite knowing how important good documentation is, it often gets put down the priorities list as deadlines approach. So recently I that enough was enough and decided to set aside a day to catch up on my documentation. My goal was to try and document the systems I had been working on recently and I figured that a day would be plenty.Â
I fired up our documentation wiki and was all ready to write down everything I knew about the systems but after an hour I’d achieved very little. After 2 hours I’d deleted everything and wanted to start again.
I couldn’t understand what the problem was. I had a hand in designing and writing the systems so I knew plenty about them. I’d been working on the systems up until the previous day so the code was still fresh in my mind. I generally don’t have too much difficulty trying to articulate what I want to say and yet I was struggling to put into words anything that I felt would be any help to anyone.
I thought if I just sat down and made a conscious effort to write documentation the rest would be easy. Turns out I was wrong. Maybe the reason I’ve been lax about documentation in the past wasn’t because I didn’t like it, but maybe it’s because it’s just damn hard.
After some contemplation I realised that I hadn’t put any planning into what I wanted to document so I came up with these rough guidelines:
- Identify your target audience. You may find that you need to write different documents to appeal to different audiences. Developers will need different information to BA’s. Trying to make your documentation appeal to everyone will end up in a document that isn’t very useful to anyone.
- Work out a rough structure before you start. Try and spend 10 minutes working out a rough outline of what you want to include in your documentation. Doing this will help you structure your thoughts as you’re writing.
- You’re final document can be as big as you want but try to keep each section within the document small and relevant. Try not to include details that are irrelevant.
- Identify what parts of the documentation are most important and focus on those first.
- Get someone from your to look over what you’ve written to make sure it makes sense to them. The documentation is every bit as much for them as it is for you
- Isolate yourself. Turn of email, unplug your phone, whatever. Just avoid yourself getting distracted as you’re going to need every bit as much mental concentration to write your documentation as you did to write the systems you’re documenting.
I strongly believe that developers should be responsible for writing their own documentation too. Who better to write the documentation for the system than the person who created it?