Strategy to Deal with Those Obstacles
Definition of Strategy
The term “strategy” is derived from the Greek words:
stratégos, which means “general,”
stratos, which means “army,”
agein, meaning “to lead.”
Strategy, therefore, by dictionary definition, refers to a plan for the overall conduct of a war or sector of it.
By extrapolation, it has also come to mean a plan for the skillful overall conduct of a large field of operations, or a sector of such operations, toward the achievement of a specific goal or result.
This is planning that is done at upper-echelon level, as, if it is to be effective, it must be done from an overview of the broad existing situation. (The reader is trying to achieve success with your product.)
Strategy is therefore a statement of the intended plans for accomplishing a broad objective and inherent in its definition is the idea of clever use of resources or maneuvers for outwitting the enemy or overcoming existing obstacles to win the objective.
It is the central strategy worked out at the top which, like an umbrella, covers the activities of the echelons below it.
That tells us what strategy is.
What does strategy do? It provides direction for the activities of all the lower echelons. All the tactical plans and programs and projects to be carried out at lower echelons in order to accomplish the objective, stream down from the strategic plan at the top. It is the overall plan against which all of these are coordinated.
This gives a clear look at why strategic planning is so vitally important and why it must be done by the upper-level planning body if management is to be effective and succeed.
What happens if strategic planning is missing? Well, what happens in the conduct of a war if no strategic planning is done?
1. Barrier #1: The reader has limited time to achieve initial successes with your product before he gives up and starts looking elsewhere, either to other documentation, or to another product.
Strategy #1: the documentation itself should be easy to find, and easy to access, and very quickly answer the questions: "What is it?", "What does it do?", and "Why does it exist?".
There are many common ways to address this, but the end result is that when the reader needs the material, it can be quickly at his fingertips, whether it be online, in the form of a pocketbook (for readers in the field), or a publication in a form that fits nicely on a shelf (or in another storage place) near the reader when he needs it. It needs to have an introductory chapter that introduces the reader to the product, and to its parts if complex.
When the reader reads the material in sequence, he can easily follow the train of thought, and continue to understand what he is reading because it is in a logical sequence: prerequisite understandings are presented first, and more complex understandings come later and build upon the basics already presented.
If the reader encounters a word or symbol he does not understand, he must be able to look it up (if the definition is beyond the scope of the material). This prohibits the use of slang or local colloquialisms.
2. Barrier #2: For any given question the reader is asking "on the path" to that success, the reader has limited time to get it answered before he gives up, and again starts looking elsewhere.
Strategy #2: Here the reader is asking a specific question, he should be able to find its answer quickly. Every second and every minute counts.
The Qualities of Good Documentation
Orientation Material Comes First
Because the reader might be reading your material in sequence, he is going to need to acquire broad, orienting understandings before narrower, more detailed understandings. Thus, orientation material should be first and in a logical sequence, with links to more detailed material for when the reader needs it. The most common questions "What is it?" and "What does it do?" should be answered VERY early in the material, preferably within the first 1 or 2 lines of text the reader sees after doing a search, or opening the web page or book chapter that contains material about the "thing" he is asking about. This should be followed immediately by "Why does it exist?" (i.e. "What problem does it solve?"), and "How does it do what it does?" in the broadest of terms (or via an easy-to-read diagram) to orient the reader, while providing links to more detailed information when he needs it.
A Thorough Reference Section Is Present
Because a reader reading the material in sequence needs to continue to be accommodated, the Reference Section normally occupies the latter part of the material. Thus the reader can read the orientation material up to the Reference Section, and then skip about in the Reference Section to answer specific questions, or to thoroughly learn each topic when he needs to, because prerequisite understandings have already been established.
When the reader has a question, he will often first look in the table of contents, skimming through chapter and section names to quickly find where to look. For this reason, the Reference Section needs to be logically organized, with intuitive chapter and section names. The first major section should present details about the "thing" as a complete whole, and if the "thing" is complex, subsequent sections or chapters need to break the "thing" down into its parts in a logical sequence. And all detail about each sub-part should be in one place, in the section where it belongs, i.e. where the reader will look for it.
Finally, when the reader has a question and has not been able to find where to look for the answer by skimming chapter and section names, he needs some other way of finding his answer, that will ultimately be successful, even thought it may require more time investment. The solution to this need is some kind of search mechanism, and to fulfill the "ultimately successful" quality, it needs to be thorough. For printed material, this is an index. For material in electronic form of small-to-medium size, this can be a word or phrase search mechanism. For larger, more complex works, the search mechanism can additionally be accommodated by an index.
But because creating an index is itself a very large undertaking (typically consuming 10-30X the time it takes to read all of the material end to end, depending on how thorough it is), the decision to create one should be made carefully, and it should be undertaken
only after the the material is in a very stable state, i.e. the writers have stopped changing it. (See
How to Create an Index for more details.)
The mind is ready to learn what it is asking questions about.
What questions is a reader new to your product going to be asking?
Once he has decided to use your product, what questions will he be asking?
After he has learned to use it but is still a beginner, what questions will he be asking?
And once he is an advanced user (and at the various points along the way while getting there), what questions will he be asking?
Good documentation answers your reader's questions in roughly the same sequence he will ask them.