Writing Code for Humans

My father used to say: “If all else fails, read the instructions!” I think that this is an accurate way to describe how people function. The first thing we do when we open a box is to toss the instructions aside and try to figure out how to use our new toy. We will puzzle through a problem, press buttons on the new camera, and assemble the IKEA cabinet our own way before we find out that that we wasted time, did it wrong, or worse, broke it.

This natural tendency is at odds with how standards, audits and such are designed and implemented. Tossing the certification instructions aside is not going to ensure that your implementation of a complex system is going to be successful.

Standards, audits, certification, labelling, and other bits that are part of a certification scheme are detail oriented and require clear, step-by-step instructions and guidance for users. 

It really helps if the stuff is clear, easy to read and works with the way humans work. But, let’s be honest, most scheme documentation is confusing, not well organized and hard to follow.

We often think of instructions as a computer program in which each step, no matter how trivial must be written and placed in its proper order in the sequence. Humans, thankfully, are not computers and we are a bit more flexible than computers. With that said, clear instructions designed for humans do help and when properly prepared it is more likely they will be followed.

So how do you write code for humans? Here are a few things to keep in mind:

1.       Understand what your user needs

Find out who is going to use your instructions and guidance; write for them. If it is likely to be an intern or junior staffer, keep that in mind. Your writing may be their first real introduction to standards and certification.

2.       Use words and graphics

Some people read the words and ignore the graphics, others read the graphics and just look at the words as if they are footnotes to the graphics. Whenever you can, give presentations that both can read.

3.       Write in the positive

It is very hard to follow instructions that tell you what not to do. Instructions are so much clearer when you keep this in mind.

4.       Tell them how their work will be evaluated or audited.

Give a clear description of how their work will be used. If it is to be audited, explain the steps in how that works.

5.       Don’t think they are stupid or that they can read your mind.

Write for readers that are smart and want to learn, that is why they are reading your work. At the same time, be aware that what is ‘obvious’ to you may not be to others, so include all the steps in your descriptions.