There was a chat about the joy of writing technical documentation (and blog posts), one person said they loved doing it, and someone else said it was often looked down as an easy job, for those that cannot code.

I see technical writing is a skill that not every one has. For example it requires empathy – knowing how someone else feels. It is a bit like breathing. Every one can do it. As a singer you need to learn how to breathe to get the music to all the audience.

There are two view of communicating

• What the audience want’s to hear
• What I want to tell the audience

I went to a presentation about Greek architecture. Most of the presentation was of pictures of the speaker and his friends sitting in cafes in Greece. In one or two pictures was some architecture. This is an example of “What I want to tell the audience”. The audience wanted to hear about architecture – and having no cafes would have been a bonus.

When you write, you need to consider why people are reading the documentation

• Is it for a narrative story? “Begin at the beginning, and go on till you come to the end: then stop” said the King of Hearts in Lewis Carroll’s Alice’s Adventures in Wonderland.
• Is it to find the answer to a question? This might involve searching for text in the document, and the reading will unlikely to be sequential.

You might want to write down a list of questions that you think a reader may have when reading your documentation. You then use these questions as headings. There is a difference between section headings:

1. Renewing a digital certificate
2. My certificate has expired. What do I need to do?

The second one is likely to be the question in the reader’s mind, and get a response “Yes – that’s it”.

What knowledge do you expect the reader to have?

If you need to include background information, put it in a section called background. The experienced person can then skip. If you mix background and useful content, then if you speed read the document you might miss the nugget.

People learn in different ways

• Some people learn best reading
• Some people learn best by listening
• Some people learn best by doing

If you can, give examples of instructions the reader can follow themselves.

Some examples of bad documentation

I hired a car. It was a modern hybrid, with a computer screen, and half the normal buttons and controls. The instruction manual for the car was hundreds of small pages long. The first 20 or so pages were about the benefits of a hybrid car. Then followed instructions for fitting a car seat. I could not find the instructions on how to use the handbrake – which was not in the index. I think I eventually found it as “Automatic brake”.

We had great problems parking the car, because it kept complaining “Key not in car” and refusing to lock the doors.

I suggested to the car hire company that they provide one laminated piece of A4 paper with big print with

• How to adjust the driver’s seat
• How to adjust the wing mirrors
• How to start the car
• How to stop the car and leave it.

Configuring a product

About 40 years ago I had to test installing CICS on VSE.

The instruction were along the lines of

• define this data set,
• define that data set,
• define this VSAM file,
• define this VTAM APPLID…
• Now start it up. “It will give a successfully started message”

There were more than 40 things you had to define.

When it failed, as it usually did, you got a message like “££BOPEN failed” and no information about what have failed to open. You had to go through every step and check the definitions.

I worked with the developer and a very good writer and we came up with a script

1. Define the minimal CICS JCL set every thing possible to no. For example DUMP=NO. There were about 15 lines of JCL.
2. Start CICS – it it fails check the definitions
3. Stop CICS
4. Define the DUMP data sets
5. Change the option DUMP=NO to DUMP=YES
6. Start CICS – it it fails check the dump data set definitions
7. Define something else, change the option, start … stop…

If it failed, then it was obvious what caused the problem. It was the definition you just added.

This was shipped as the install documentation and customers loved it.

A few years later I was involved in the product again, and all of the useful stuff had been stripped out, and the instructions were like the original set of instructions. The tester had his set of “testing JCL” which he ran to make sure it worked.

The tester did not try to type the definitions in with all of the typical user errors. You need to have people with the appropriate level of skill to test the product, and read the documentation. Appropriate might be skilled in the platform – but low knowledge about the product. Having people skilled in the product doing the basics is wrong. We had managers do the install – that was great because they did not understand the technical level.

You need to approach testing and documentation from the user’s perspective – not from your perspective – this is the empathy I mentioned above.

Don’t repeat … point to it, and add value

I was researching how to do something, and there were many articles about how to do it. Some were short, some were long, and they all covered the basics – but not many articles covered the next step after the basics.

It would be better for every one if some of the people had written

• “This topic is well documented here… so I will not repeat it. Following on from this, the next, more complex thing to do is …”.

There are many articles on how to create a digital certificate on Linux. My follow-on questions include

• How to I use a second certificate, or how to I use a second certificate authority certificate in the same scenario?
• If I want to invalidate a certificate – how do I do it?
• If my certificate expires what do I need to do.

These questions are not usually covered.

Signposting

If the whole content fits on one page, you may not want signposts. If it is a long document (more than a page or two) to need to show the document structure.

You need a table of contents, with links to the text to help people understand the document layout, and where to go. At the top of a blog post may be text like

• Setting up the Certificate Authority
• Setting up the certificate
• …
• If I want to invalidate a certificate – how do I do it?
• If my certificate expires what do I need to do?

Give the high level view and then go into more detail

For a complex project start high and work your way into the complexity. For one very complex presentation I started at the high level, then went through it again in more detail, and then a third time in great detail. At each detailed step the audience knew where they were going, because they had already been along the path.

I went to a presentation on an introduction to a certain data protocol. By slide 3 we were looking at all of the fields in the data header. I did not know what the protocol was for… so knowing all the details of fields was wasted on me when I didn’t know what the protocol did.

Someone may not know what you know.

Ensure that you explain terms, or the first time you use a term which may not be generally known; give a link to a definition. Those that know what the term means, will not go to the link. Those that do not know – can go and find out.

I have been working on a presentation about TLS (Transmission Link Security). I got to a point where I had to describe the different sorts of hashing available. I realised I needed a page explaining what Hashing data entails before describing TLS.

Before describing the very complex description of the TLS hand shake. I described how a conversation between someone and the Milk Management team in the EU might work.

• You: (phoning Brussels) Hello I speak English and French, I would like to talk to someone in the Milk department
• Them: Hello – we will speak English, my name is… Who are you…

Because the concepts were similar, explaining the TLS handshake was much easier.

Keep it simple

Explain what is needed and do not include information which may only confuse, or may never be used.

Someone explained a protocol to me it went along the lines of

• At offset 0 is an eye catcher ABCD
• At offset 4 is the length of the control block
• At offset 8 is the function 0 = start, 2 = query, 3 = terminate
• At offset 12 is the date…

The reply has

• At offset 0 is the eyecatcher
• ..
• At offset 8 is the return code – 0 means it worked successfully

At the introduction level I do not need to know the offsets or the values. Several values are not of interest until I start trying to program the protocol,

My description of the protocol was like

There are several fields sent to start the session. The important one is

• …
• function. This has the value start, query or terminate
• …

The response has several fields. The important one is

• …
• return code – 0 if it worked else a code you can look up HERE to see why it failed.

Afterthoughts

• I saw this article as a sequential read through – perhaps as a basis for a talk at a conference next year?
• It is a long article. I should have used sign posts, or section headers at the top.