Howto - Write documentation

[TomVanDoo]

I know,

The last thing any developer, technical, or even functional profile wants to do, is write documentation. Still, the documentation is a vital deliverable, and some companies even refuse to pay the final invoices if the documentation is sub-par.

This isn't a blueprint

They're right you know. Often times, I see documents containing different chapters for all the custom tables, with a list of all the fields. I've seen webservice definitions which are basically just an Excel sheet with bright colors and a bunch of technical names scattered around with no explanation whatsoever what the service is supposed to do. Sometimes, I come across design documents with nothing but pseudo code.

This is all useful information that must definitely be in a technical document, blueprint, design or whatever, but it must never be the only information. The developer in the end will need the structure of the table. He/she will need to have an idea about the expected coding and he/she will need to know how to implement the webservice, proxy, handler, whatever. But they also need to know the goal of what they are doing. They need to know the story.

If there is no coherent story behind all this data, than that is exactly what it is. It's just, pure metadata. Before you can actually consume the data, you need to see how it links together. You need a coherent story, which turns the data into information. Information which you can consume, and apply and over time, turn into wisdom. but let's not go there just yet. Let's first see how we can make the data manageable and turn it into information.

Some pointers

1) There's a very easy tip I would like to share. Don't write a bunch of technical buzzwords. Instead, tell a story. Tell a story in which you put the end-user as the central actor. My first mentor always told me, "good documentation reads like a good book". By doing so, you will ensure that the implementation is also done with the end-user as crucial factor in the end. It will result in a process that is oriented towards the user and most of all, make it clear to the developer what his contribution actually is. Better understanding of the expected result, leads to deliverables that are better in line with the expected result.

You may argue that you write the specification for the developer and that you will explain what you mean to him. Never forget however, that in 3 years, someone else will have to make a change to those developments, and that you might not be there to explain your cryptic listing of data.

2) Let someone else read your document, preferably someone who is not involved in that area of work. If he/she comes back and says: "I have no idea what you are trying to explain here" than you must go back and redo it.

3) Don't only describe the happy route, but also describe how the end-user can get frustrated when he deviates from the happy route and ends up in the "dark wood of error". Describe how to bring the user back on the happy track before he gets lost.

4) If you're going to describe the necessary tables, include a data model in MS Access. It makes life so much easier and is so much more understandable than just a listing of tables and describing: "table A links to table B via key fields ID and Hullapalooza". Seriously: visualize!

5) If you're going to visualize, don't step in the rescaling trap. By that, I mean that people insert giant charts in the word document, but rescale it to make it fit and by doing so, it becomes unreadable. Add the image, chart, diagram,... as an attachment, so that the reader can open it in full scale and full quality. Also remember that the reader may not have the right tool to consult the document, so consider making it available as a PDF too.

And while you're doing that, take some time to sit together with a User Experience consultant, create some screen mockups, and put them in the document as well. (in line and as attachment)

6) Use the word styles for formatting. They help you in making uniform looking documents and they allow for automatic generation of a "Table of Contents" or a "document map". these are two super-useful techniques to quickly navigate lengthy documents.

7) If your document exceeds 25 pages, consider putting in a management summary.

😎 Keep your document and story up-to date!  Nothing more frustrating to finally find the documentation on the report you have to change and then discover that the spec is not in line anymore with the implemented reality.

9) Organize your document repository in an intuitive way and remember that in 3 years time, people still have to find your documents. (Consider putting them on the development environment itself to bundle them together with the actual system work) Avoid root folder names like "09_271_X_9". How about simply giving your root folder the same name as the project which you are working on, maybe preceded with a number for the historic sorting like: "092) Project"?

I know, crazy idea right? Yeah, I'm a real goofbag. 🙂

ROI

These are the pointers I (mostly) follow myself. I've had very positive feedback from clients already, because the documentation is actually readable to anyone and it still contains the technical information required by the technical profiles. On top of that, it provides a base for user manuals as it tells the story from the user point of view.

These tips are not only for Development specifications, but they are equally important for blueprints, functional descriptions, user manuals, training material and so many other types of documents you have to write on a project.

It might look as if you're going to spend more time on the documentation this way, but in reality, you're actually going to spend less time explaining and reworking the doco and your testing plans and user manuals will get a head start.

Also appeared on my personal blog

Edit: corrected the whitespaces between paragraphs