Ep 13: I Love Docs, I’ve Always Loved Docs

GIF from Jupiter Ascdending. Dialog: I love dogs, I've always loved dogs

The title is a reference to Jupiter Ascending, the wonderfully fun and ridiculous Wachowski film. I highly recommend it!

Lets talk about something else I really enjoy at work: documentation. This was a episode I had in the back of my head but after an interesting twitter conversation I decided to move this up the schedule.

Writing documentation is often left as an after thought, not enough time given to compile and write out good documentation. And even when it’s written, making sure it’s kept up to date is something else that’s often neglected. Or someone sets up a wiki or a confluence and there’s no real maintainer or editor and documentation is piecemeal, and a bit crap. It’s much harder to go and fix someone else’s bad docs than to write your own, I think?

Documentation is important, whether it be for contributing to an open source project, internal documentation, or user documentation. Good documentation is even more important – documentation that is not helpful or usable is probably worse than not having anything at all because confusing a user with bad documentation is going to frustrate them more than having nothing to read and them just learning as they go along or googling for the answers.

So, what goes into good documentation? That’s quite a big question, with lots of different things to take into account, but I’m going to give a brief overview of the basics here.

I think the main things to consider are:-

  • Purpose
  • Assumed knowledge
  • Format
  • Formatting

Each of these have their own considerations:


Fairly obvious, everything needs a purpose. If you don’t know why you’re writing docs, you can’t write then effectively.

You need to figure out who, what, where, when, and why?

This will inform pretty much all the next steps and decisions made.

Users require different knowledge and language to devs, and different users may require different knowledge depending on how they interact with the system. Are there different user roles and permissions? Are there dependencies?

Assumed Knowledge

If your docs are aimed at developers then you can assume certain bits of knowledge about coding or using libraries or apis; or you can possibly assume the devs will be able to google/ask for assistance for parts of the docs.

For user docs other than domain knowledge, what can you assume? I prefer not to assume anything – it’s easier to skim what you know that not find what you don’t know. But you may be able to assume some knowledge of the system, it’s a decision to be made before you start writing.

Format and Formatting

Electronic means easier to update, centralised, and can be more accessible. On the other hand, you need to consider who updates it, how to update it, version control, etc.

Hard copies can be inaccessible to users who are visually impaired, hard to update and review, copies are not centralised.

This can be anything from layout; following user journeys.

Formatting can be anything from using screenshots, bulleted lists, annotations, alt text.


Keep it short and informative. I have a biochemistry degree, and one of the assignments that sticks in my head was writing a precis. We were given an article from a scientific journal, and we had to summarise it in under 1000 words. The original paper is around 4500 words. It was hard, deciding what was really needed to convey the contents and meaning of the paper, and what could be cut without changing the context of the paper. Thankfully it wasn’t a write up of an experiment or research; that would’ve been even harder to summarise while keeping the overall results on findings of the paper correct. I’ve got a link to the paper and the precis here, if anyone’s interested. I’ve read the precis, and I’d like to think my writing has got better since then, there’s definitely choices I’d make just to the way I’ve written things there, even without me re-reading the original paper.

That’s a tangent, but my point is that summarising and shortening things is a skill, one that needs to be practised. Writing itself is a skill that can really only be honed by practising and this is as true for technical and factual writing as it is for fictional writing (though the methodology and skillset is different). You’ve just got to keep writing, whenever you can.

Finally, go read this, its brilliant: http://stevelosh.com/blog/2013/09/teach-dont-tell/

Leave a Reply

Your email address will not be published. Required fields are marked *

Tags: , , ,