The Art of Writing Implementation Guides

The term Implementation Guide is a "term of art" in my world.  It has a particular, specialized meaning.  It's a document that principally tells its users how to implement and use a standard.

But if you get right down to it, the term itself also has a meaning that comes quite simply from the meaning of the words.  It's a guide to implementation.  Consider the key word here "Guide".  It's both a noun and a verb, where the noun describes one who "guides", and a guide is one who:

1. leads or directs,
2. exhibits or explains, or
3. directs the course of another.

If you lead, direct, exhibit someone, without providing an explanation of why your course is a good one, you have failed.  Yet so many implementation guides leave out the rationale for doing things the way that the guide suggests.  This is the art of good implementation guide writing.

A simple formula for writing is "Do this, because that".  The "because" will help explain your rationale.  

Have consideration for the audience for your implementation guides.  Most of your readers will not have gone through the discourse that you have on the topic at hand.  A guide should explain why when the answer isn't immediately obvious so that users can follow your reasoning.  The big challenge for implementation guide authors is understanding what isn't immediately obvious.  Your reader isn't a five year old, the answer has to be better than "because I said so (or a team of experts said so)."  But as you write, do think like a five year old, and ask yourself why to go with everyone of your wherefore.

Consider the following example:

1. A measure shall have a human readable name.
2. The name shall be unique among measures published by the same organization and should be unique from the names of measures published by others.

Compare it with these instead:

1. A measure shall have a human readable name that explains what is measured.
2. The name shall be unique among measures published by the same organization so that users can distinguish between different measures.  It should be unique from the names of measures published by others for the same reason, but it is understood that this is not under the control of an individual publisher.

It only takes a little bit more effort, but including your rationale does two things: It educates, explaining your reasoning to your audience, and it sells that audience on the constraints that your guide imposes.  It's much easier to get good implementations when your audience agrees with your reasons, and also remembers them.

Sometimes a guide has to make arbitrary choices.  In these cases, simply explain that while there are two options, the guide chooses option A over option B to ensure that the thing is done in only one way.  Note that if there are two choices, A and B, and you've chosen A, you've said "Do A, NOT B".  It might be helpful to say it both ways as an aid to memory.  In these cases, express the positive case first because the addition of a negative adds cognitive effort.

Two ways are commonly used to report an organism detected, however, this guide only allows for one of these to ensure consistency. This guide requires that the organism being identified be encoded in the test code, and the test result be encoded in the test value to ensure consistency among implementations.  An implementation shall not use codes which express a test for an organism, followed by a value describing the organism being tested for.

If you must allow both choices, consider explaining why, and when it is appropriate to pick one vs the other.

Client applications may use XML or JSON to interact with the server.  The client should choose the implementation format which best fits their processing model. JSON is more compact, but sometimes harder for a person to read.  XML is more verbose.  

FWIW: I know this better than I follow it in my own writing.

   Keith