2.5.3. Tactics
2.5.3.1. Definition of Tactics
The term “tactics” is derived from the Greek words
taktikós, adj. “of ordering or arranging, of ordering troops in combat,”
taktós, “ordered, prescribed” (verbal adjective of tássein — Attic táttein — “to draw up in order [as troops, ships], post, station, place in order, prescribe, assess,” of uncertain origin)
+ -ikos, “having the character or form of; being”.
Tactics are the science and art of disposing and maneuvering forces in combat, or (more applicable to our topic) the art or skill of employing available means to accomplish an end.
2.5.3.2. Sequence of Steps to Produce that Documentation
The sequence of producing good documentation almost never follows the sequence of a reader reading it. In fact I think I can confidently say that it never follows that sequence. The reason for this is that typically, the writer’s thought sequence starts with the general and then dives into deep detail, cyclically, over and over again until the documentation material is a complete and valuable, final product.
How does the writer restrain himself from ending up with the thought sequences as they came out of his head?
2.5.3.2.1. Create a Plan
To have such a thought sequence, but still wind up with well-organized, high-quality documentation (that has the qualities described in the Qualities of Good Documentation section), one needs a detailed plan, ideally very early on in writing that documentation: an outline or definition of the navigation tree (table of contents) should be fleshed out and made fairly firm before much writing has taken place. (Note that the term “navigation tree” applies whether the end documentation will be in electronic or printed form, since chapter and section titles are most definitely part of what the user searches to most quickly find answers to questions.)
Without such a plan, the quality of the whole drops as the material “evolves over time” and an in-sequence reading begins to have problems, such as logic gaps, and material about a particular topic can (and does) become scattered. This can be the case for collaborative (e.g. GitHub) projects when lack of such a plan was not made known early to all the writers involved. The result of this is that the content begins to deviate more and more from the ideal scene described in the Qualities of Good Documentation section earlier. Content is duplicated in multiple places, and the organization (a.k.a. usability) of the whole document gradually goes downhill until some organizing force intervenes. One of the factors that causes this to occur is that without such a plan, the writer follows his cyclic train of thought across a span of days, weeks, months or even years (several of the volumes of The Art of Computer Programming, by Donald Knuth took years to complete), instead of following the reader’s needs (an organized easy-to-read, easy-to-use whole).
When such a plan has not existed for a long time, the documentation builds more and more content that gains inertia, and thus becomes more and more costly (in terms of time and effort) to fix.
2.5.3.2.2. Work From that Plan
Having a “navigation tree” (or table of contents) plan helps to enforce that both the orientation material and the details both end up in the right place: when the writer is in the orientation material and his train of thought dives into details, he can quickly realize he is writing details that don’t belong in orientation material and move them to the Reference Section where they belong, to the one detail section covering that topic, in a way so as to make that detail dovetail nicely with the rest of the Reference material. And vice versa when his train of thought goes the other way — from detail to basics.
2.5.3.2.3. Use Only Terms the Reader Knows or Can Easily Look Up
The writer should never use terms that the reader cannot easily look up, given the resources currently available to him. Use of slang or local colloquial terms or phrases (both British and Americans have such terms and phrases) will defeat your purpose.
2.5.3.2.4. Ensure the Reference Section is Complete First
The Reference Section should itself be in logical sequence: more basic concepts first with more complex concepts later that build upon the basics. Its page titles and subsections should be intuitively titled to help the reader skip over concepts which he already understands or are not relevant to his immediate questions. Burying concepts in prose and verbiage demands more time from the reader seeking answers to specific questions.
Each subtopic should have logical boundaries and the writer needs to find the discipline to stick to those boundaries, whether it is a subsystem of a larger machine or of a software library. It needs to be thoroughly documented, so the reader can find answers to all questions he is likely to ask (based on what type of audience he is and thus his purpose for searching). Simultaneously it should only refer to (as opposed to including) details that belong in other subtopics: put a link in the subtopic to “the other detail” and keep the other detail in the topic where it belongs – where readers will look for it.
Reference sections should be comprehensive. In other words, it should be a thorough “thought download” from its designer in a logical sequence so that the reader can achieve success with that “thing”, whether he be a mere “user”, a “maintainer”, or perhaps may need very deep knowledge as an “overhauler”. (Note that I am using general terms that can apply to software or machines.)
It is a common practice to have 2 different publications: one for end users, and the other for maintainers, as is successfully done in the automotive world. And if you are doing this, then be aware of when your mind goes into the level of detailed that most end user will not need, that such material should be relegated to the maintainers publication.
As the writer’s thoughts cycle back to the general (introductory, orientation material) from the detailed, record that material in places where the orientation material will be. Remember: follow the navigation tree plan.
2.5.3.2.5. Write the Orientation Material
Once the Reference Section is written and well organized (and fairly stable so you can supply links to it that are not likely to be broken before your writing is complete), now is the time to write the orientation material.
Try to see it from the view of a reader new to your product: he needs a bridge from knowing nothing about your product to being ready to tackle the reference section. If you are not already good at it, you will need to become good at looking at the topics you are writing about from the new reader’s point of view: as if you know nothing about them. When you are successful at doing this, it will be clear how to guide your reader through each new understanding, building on what he already knows.
Make a list of prerequisite understandings he will need before he arrives full time in your Reference Section, use it as a checklist, and make sure the path to each understanding is covered in a gradient sequence so complex understandings build upon more basic ones.
Start with orientation about your product as a whole. Answer The Basic Questions very early in your material to orient the reader, while providing links to more detailed information when appropriate.
“The basics” of a thing will, by necessity, be at the beginning of the Reference Section for that thing. A little repetition is okay, but a lot is a sign of needing to move detail to its one place in the Reference Section and provide a link to it instead of repeating.
Create chapter and section titles that are intuitive so that the material is skimmable. This helps the reader skip over concepts which he already understands or that are not relevant to his immediate question(s).
Be brief. Burying concepts in prose and verbiage demands more time from readers seeking answers to specific questions. Save your reader’s time by writing like a newspaper instead of a novel. Specifically:
Headings — should be descriptive and concise.
Hyperlinks — should surround words that describe the link itself (and never phrases like “click here” or “this page”).
Paragraphs and list items — should begin with identifiable concepts as early as possible.
Include examples when they will empower the reader. Many readers look first to examples for quick answers, so including them will help save these people time. Try to write examples for the most common use cases, but not for everything. Too many examples can make the documentation less skimmable. Also, consider separating examples and tutorials from more dense reference information to further help readers skim.
Be consistent in language and formatting: the more editors you have, the more important a style guide becomes in facilitating consistency. Consistency also helps make documentation skimmable and beautiful.
Remember: the final result of the introductory material is that it provides a bridge from knowing nothing about your product to being ready to tackle the Reference Section. You are “holding the reader’s hand” to guide him through A) acquiring prerequisite understandings while B) discovering where to find more detail when he is ready for it.
