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.

 

 

 

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 final product.

 

How does the writer restrain himself from ending up with the thought sequences as they came out of his head?

 

 

 

To have such a thought sequence, but still wind up with well-organized, high-quality documentation (that has the qualities described in the Strategy section), one needs a detailed plan very early on in writing that documentation:  an outline or definition of the navigation tree should be worked 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 names and section names 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".  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 Strategy section above.  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 to fix.

 

 

 

Having a "navigation tree" 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 orientation material.

 

 

 

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.

 

 

 

The Reference Section should itself be in logical sequence and more basic concepts first with more complex concepts later that build upon the basic concepts.  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 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 details that belong in other subtopics:  put a link in the subtopic to "the other detail" and keep the other detail where it belongs.

 

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.)

 

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.

 

 

 

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 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.  Make a list of prerequisite understandings he will need before he arrives full time in your Reference Section, 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.  What is it?  What does it do?  These two questions should be answered very early in your material.  Follow this immediately with the answer to, "Why does it exist?" 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 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 place in the Reference Section and provide a link to it instead of repeating.

 

Create chapter and section titles are intuitive so that the material is skimmable.  This helps the reader skip over concepts which he already understands or are not relevant to his immediate questions.

 

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:

 

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.

 

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 for when he needs it.

 

 

The remainder of this page taps heavily on the wisdom from https://www.writethedocs.org/guide/.  Some of it is copy/pasted and edited to match the context of this article.

 

 

 

Give readers the information they need, but not too much.

 

First, know which of these common audiences you are writing for:

 

 

Very early, answer the questions, "What is it?" and "What does it do?", 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 a "link" to more detailed information when he needs it.

 

Include one or more example use cases for your product.

 

Beware of overusing Frequently Asked Questions (FAQs) as documentation. Although FAQs can be useful starter documentation for new projects until you have time to write better documentation, FAQs quickly outgrow their use due to many drawbacks:

 

When examples will empower the reader, include them.  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.

 

Keep it current.  Consider incorrect documentation to be worse than missing documentation.  When a product changes faster than its documentation, the users suffer. Keep it up to date.  Make every effort to write content that is version-agnostic and thus in less need of maintenance. For example, generalize version numbers of software when they occur in tutorials (such as extracting a source code tarball with the version number in the file name).  Some users will remain with older versions of your product, and thus require older versions of your documentation.  Proper documentation platforms will accommodate such needs gracefully.

 

 

 

A "source" refers to a system used to store and edit content.  Examples of sources include: text files written using reStructuredText or Markdown, HTML content in a CMS database, help text stored within strings in application code, code comments to be assembled later into formalized documentation, and others too.

 

For software documentation, all sources should be nearby and unique.

 

 

Store sources as close as possible to the code which they document.

 

Give developers systems that allow them to easily make documentation changes along with their code changes.  One way is to store documentation content in comment blocks within application source code.  Another is to store it in separate text files but within the same repository as the application’s source code. Either way, the goal is to merge (as much as possible) the workflows for development and documentation.

 

 

Eliminate content overlap between separate sources.

 

Storing content in different sources is okay, as long as the scope of each source is clearly defined and disjoint with other sources. The goal here is to prevent any parallel maintenance (or worse — lack of maintenance) of the same information across multiple sources.

 

 

 

A "publication" refers to a single, cohesive tool that readers use to consume documentation.  It may be static or interactive — digital or paper.  Multiple publications may be created from a single source (such as web and PDF versions of the same manual).  Although rarer, multiple sources may be used to create a single publication.  More examples of publications include:  API reference, man page, command line  --help  output, in-application help tips, online tutorials, internal engineering manuals, and others too.

 

Each publication should be discoverable, addressable, on a gradient, complete and beautiful.

 

 

Funnel users intuitively towards publications through all likely pathways.

 

Try to identify everywhere the user might go looking for documentation, and in all of those places, insert helpful pointers for them to find it.  Documentation need not exist in all of these places, just pointers to it.

 

If a user manual is published in the woods, and no one is around to read it, does it exist? Discoverability says “no”.

 

 

Provide addresses to readers that link directly to content at a granular level.

 

The ability to reference specific sections deep within a body of documentation facilitates productive communication about the documentation, even with one’s self.  These addresses can take the form of URLs, page numbers, or other forms depending on the publication medium.  Readers may wish to bookmark certain sections, share them with other users, or provide feedback to the authors.  The more granular this ability, and the easier it is to access, the better.

 

 

Content should be ordered to cover prerequisite concepts first.

 

Can a reader follow your entire body of documentation, linearly, from start to finish without getting confused?  If so, the documentation's gradient is perfect, which is great, but not always possible.  It is something to strive for, especially in tutorials and examples.  If you have separated your tutorials and examples from the reference documentation, then put the tutorials and examples first.  Then, content within the reference information section may be ordered alphabetically or topically without regard to prerequisite needs.

 

The goal of gradient ordering is not to encourage readers to consume your documentation linearly — rather it is to help them narrow their search for information when filling in gaps in their knowledge.  If a reader arrives with some knowledge of your product and begins reading the documentation at the 25% mark, they are likely to "rewind" when confused.

 

 

Within each publication, cover concepts in full, or not at all.

 

Picture some documentation of software like a map of a neighborhood.  If the map displays roads, readers will expect it to display all roads (which exist and are of the same type as those being displayed).  Perhaps the map does not display railroads, for example. Thus, a reader approaching the map to look for railroads will find zero and then seek a different map — but the map is still "complete", even with this shortcoming.  "Complete" does not mean that the map must describe all characteristics of the land.  It means simply that, for the characteristics it chooses to describe, it should describe all of them.  A map that displays fifty out of one hundred fire hydrants in a neighborhood is worse than a map that displays none.

 

As a good example,  iconv  is a command line tool for working with character encodings.  Its man page covers all of its available options but none of the possible character encodings accepted as values to these options.  Instead, the man page instructs the user to run  iconv -l  to produce a list of character encodings.  In this example, the man page and the list are separate publications, both of which are complete, which is good!

 

Publishing partially completed documentation must be done cautiously.  To avoid misleading readers, make every effort to clearly state, up front, that a particular concept is only covered partially.

 

 

Visual style should be intentional and aesthetically pleasing.

 

Aesthetics don’t matter to everyone — but (consciously or not) some readers will struggle to find comfort in documentation that lacks attention to visual style. Even in text-only documentation such as  --help  output, visual style is still present in the form of spacing and capitalization.  If visual style is not important to you personally, then consider soliciting stylistic improvements from others for whom it is.

 

 

 

A "body" refers to the collection of all the publications within a product-development project and any of its sub-projects.

 

A documentation body should be comprehensive.

 

 

Ensure that together, all the publications in the body of documentation can answer all questions the user is likely to have.

 

We can never create enough documentation to satisfy all questions, however obscure, that might arise from users — but satisfying the likely questions is certainly attainable and thus should be the goal of a body of documentation.  "Likely" is admittedly a blurry term, but it is also relative, which means that a body of documentation which answers very unlikely questions while failing to answer likely ones is somewhat out of balance.

 

Answering some questions may require the user to read multiple publications, which is okay.