Writing documentation can be in your own interests

Introduction

Some people take the agile manifesto‘s

… We … value … working software over comprehensive documentation

the wrong way.  They think it means

We don’t value documentation

This is:

• a) not the same as what the agile manifesto says;
• b) wrong, even if you act purely from self-interest.

There are at least two selfish reasons why it’s good to write documentation.

Freedom to do new interesting work

If you’re the only person on your team who understands the wizard-level code you’ve written, who is the person that will have to work on it forever more?  Even when it has stopped being interesting and fun, and becomes more of a chore?

If there’s no documentation, your team-mates or boss can reasonably reject your suggestion that someone else work on it.  If there’s decent* documentation, your suggestion will hold more weight.

This will then give you the chance to move on to new stuff, that’s still at the interesting and challenging stage.

Being properly appreciated

You do code wizardry.  If it’s baffling to your colleagues, they’ll be impressed by what it does and daunted by (and give up on) trying to understand how it does it.

However, I think that a programming team is different from a magician and their audience.  Unlike a magician, you don’t want to keep the details of how the trick works a secret.

Your colleagues should get to appreciate the trick twice: first from the outside, when they see the amazing effect, but also a second time from the inside when they learn and appreciate how it’s done.  They are likely to start with enough knowledge that only a reasonable* amount of documentation is needed for them to reach a deeper understanding of it and hence an admiration of your wizardry.

So what documentation should I write?

I have used terms like decent and reasonable to describe documentation, but what do they mean?

I think this is another example of a cunning ploy advocated by Paul Boag: use your user experience (UX) skills on your colleagues.  In fact, this is an area where UX thinking is much easier than usual, because you are very similar to the users (of the documentation, in this case), and have easy access to them.  If nothing else, what documentation would you find useful when coming to unfamiliar code?

If there’s too much of it then:

1. You probably wouldn’t read all of it before getting bored
2. You would worry about it being out of date, which can be worse than having no documentation

So this isn’t a case where bigger is always better.  The documentation I tend to find most useful at any scale (code comments all the way up to system stuff):

1. Gives me an overview of the whole thing that’s quick to understand.  This helps me know where to start looking for more detail.  It also gives me a framework on which to hang the detail when I find it, rather than the detail sloshing around with no home to go to in a confusing jumble.  Pictures can be very effective here – even photos of diagrams drawn on whiteboards, although I’ve never put pictures in my comments.
2. Helps me to know why things are a certain way (and why they’re not different ways).  This is much more likely to be (a small amount of) text rather than pictures.
3. Pulls together information into one place about cross-cutting concerns.  I could probably understand them eventually, but would have to look in lots of different places and each place would contribute only a small bit of extra understanding.  This could be things like security, error handling or a protocol / framework that you have to comply with.

Summary

Writing documentation can make your life better, even if you’re being selfish.  It increases the chance that you get to work on new and interesting stuff, and increases the chance that your colleagues realise how amazing you are.

There’s a Goldilocks aspect to it: you can have too much as well as too little (plus the wrong stuff too).  Pointing your UX skills towards your colleagues (or even yourself) will help you know how much and what to write.