A Quick Guide to Documentation



Why document anything? It’s not like anything would catch fire, would it? 

“At the end of August 2016, it was announced that the airport had missed an internal deadline and that the permissions for the next phase of construction could not be issued. This was because the fire protection system for the connection between the airport and railway station lacked sufficient documentation.” [source]

Maybe you’re not building an airport, but you probably need to write at least a few things down.

At the end of the day, documentation is simply communication. Communication between you and your colleagues, between departments and offices, between designers and developers, between engineering teams, or even between your former self and your future self.  It helps people remember things, communicate efficiently and consistently, reduces gatekeeping, and saves precious time explaining things and transferring knowledge. And of course, your airport won’t be delayed!

What should you write down?

Anything that is asked repeatedly is usually a pretty good candidate. Consider what someone new reading it wants to know. Document decisions, instructions, incidents, rules, responsibilities, processes, and progress so that everyone understands clearly how you got to where you are and where you’re going.

When should you write it?

Document with purpose. If you find yourself explaining something over and over, this is the time to consider writing it down so that you can just point someone to the document and answer further questions. If you know you’re going to need to document a process, keep notes along the way rather than do it all at once at the end. And if you are collaborating and brainstorming, write it down while it’s happening, so that you can quickly summarise the results when decisions are finally made.

Where should you put it?

Keep things organised and accessible and ask yourself where you would look for something when you decide where it should go. Put things close to the source; code documentation should go in the code, development guidelines in the README of the repository, etc.. Break long documents up into topics and reference them via an index.

What shouldn’t you write down?

Consider what you really need. Try to avoid documenting things that change rapidly; someone or something will have to own the documentation and update it accordingly. Can you automate that task? Can you assign the responsibility? Will it get done? Outdated information is worse than none at all; if someone can’t find what they’re looking for, they’re more likely to ask for clarification than if they’re presented with an answer that they don’t know is out of date. Also, make sure your texts are searchable so that people can find what they need when - and only when - they need it. 

Be brief.

A summary at the top of each page might answer superficial questions and help someone decide if they should dig deeper into the rest of the document. Don’t repeat yourself. Link documents to each other so that readers can reference more information if they need to. Don’t forget to proofread and edit.

Word is bond.

If you write down a practice or policy, expect that people will point to it as if it were law. Language is important here; if something is not rigid, then the wording should reflect that, and vice-versa. Likewise, if you never wrote something down, don’t expect anyone else to know about it.

Know your audience.

Be #humble. Not everything is self-explanatory and not everyone has the same background/level of knowledge. If you’re not 100% sure everyone reading your document will know what that abbreviation or term means, type it out or add a reference. Beware of bad grammar, punctuation, and especially humour in your writing. Someone could easily misunderstand, especially if they’re unaware of the context around what you’re saying, new to the topic, or a non-native speaker. Not only can this lead to misunderstandings, but the confusion can often make people feel excluded or inadequate. If possible, it’s always good to ask someone not involved to take a quick look and report if they understand what you wrote. Often our own background knowledge makes it hard for us to write documentation which is fully understandable.

I hope this was #helpful. Go forth, and document! Hopefully nothing will catch fire.

Already working at Zenjob?

Let’s recruit together and find your next colleague.

  • Alexandra Rachner
  •  Alex Paradise Wright
  • Alicia M‘bayo
  • Alina Chlebowska
  • Anastasia Chamo
  • Anna Krevnik
  • Anya Stühler
  • Arthur Henrique Eggert
  • Arvind Arora
  • Ben Tober

Career site by Teamtailor