some of the technical documentation I own

some of the technical documentation I own

I’m writing documentation in my paid job at the moment: finishing up a couple of projects and leaving breadcrumbs behind so that those who come after (quite possibly me) will have clues about how the software works. I thought some notes on how documentation works might be interesting*.

When To Write Documentation

There are three options** about when to write documentation:

at the beginning. Writing the documentation first might sound strange, but it’s quite an effective way of defining the public behaviour of the system.This is what I write first if I am making a new command line tool, for example. Having the behaviour written down like this can be very valuable in generating tests.

during development. Sometimes a system’s behaviour is only fully defined during its development (not unlike discovery writing of fiction), so writing the documentation for the system as you go along can be a sensible way of capturing some of the decisions made. Writing down notes on process and design really has to be done during development, of course, and comments in the code also***.

after it’s all done. The system is finished and working****. Now you can write down all the specifics of what it does and how. This is actually the traditional time to write documentation, where a designated technical writer will come in to describe the system, but it has its problems: the system may be functioning, but the people who developed it are often being pulled in other directions which means they’re not focussing on the project being documented any more.

At least part of a decision about when to write documentation will driven by the methodology used to develop the project. A project following some version of the waterfall approach might write design documentation at the beginning while deferring user documentation until the end, while an iterative or agile approach would likely do exactly the opposite (within an iteration, at least) since user docs are a strong source of test cases.

What To Put Into Documentation

The content depends on the audience for the documentation. User docs will describe the system’s UI and outputs, while design documentation will describe the system architecture and decisions made. The content may also vary by the form of the documentation: documentation is not just textual material in a document – it can be diagrams, pop-ups or cheat sheets within the software, and so on. Design artifacts such as diagrams and state tables may be valuable documentation in their own right.

How To Write It

The trick for me with writing documentation is to find the narrative: what story does the user or developer need to know in order to understand the system?

For users, this can start with a cookbook of ways to use the tool, or describing wok flows the system supports. Tell the user what it is that the system will do for them.

For developers, again it pays to start from what it is that the system is intended to do. Refer back to use cases to link the system features back to the system intent – you end up with solid justifications for system behaviours and a stronger framework for understanding how the system functions.

I would highly recommend against explaining everything before you begin, though. Have a glossary by all means, but explaining concepts too early is a great way to lose your readers, just as it is in fiction. Including reference material in user doc is good, but having the reference material be the only content makes it hard to learn from*****.

This has been a very brief excursion into the world of technical documentation. Are there any forms of writing you do which you don’t consider part of your main practice but you approach in a narrative way?

[*] docs are not widely read or often well-written, but they’re still necessary no matter what we may hope.

[**] I have deliberately omitted the fourth option of not writing any documentation. I have been down that road and it ends in darkness and pain.

[***] being made to put comments into code after the fact is distressing.

[****] which doesn’t having no bugs so much as having no show-stoppers.

[*****] necessary counter-example: I learn new computer languages from reference docs rather than tutorials, because the tutorials often spend too much time explaining basic concepts which I’ve known for *mumble* years.

Leave a Reply