# Technical documentation summarized

All [technology](technology.md), proportional to the details necessary to operate or [service](adequate.life/fix/) it, requires some form of written [language](language.md) to indicate how to use it.

Technical documents only come from a few possible types of people:

1. The [designer](engineering-design.md) wanted to make life easier for their product's users and maintainers.
2. The maintainers wanted to make life easier for the users after [fixing](https://adequate.life/fix/) something.
3. Users were passionate enough about the continued use of the product that they created their own reference for it.

Technical documentation can be extremely difficult from how advanced the writing has to be, but it's absolutely crucial relative to several factors:

1. How bad things will get if the thing stops working.
2. The scarcity of alternative approaches that don't use that particular piece of technology.

Whenever the [design of the interface/hardware](engineering-design.md) doesn't communicate the concept explicitly (which is *extremely* common), the user needs the software engineer to communicate exactly what the user can do and precisely how to do it.

- For this reason, technical people need to understand [how to write well](language-writing.md) or get assistance from others who are skilled at it.

The absence of good technical writing sabotages the entire community around the product:

- Other technical people who have to work on the project will spend countless hours of rework just to figure out what the original creator did.
- Non-technical people in positions of [leadership](mgmt-1_why.md) and [decision-making](decisions.md) will have trouble knowing exactly what to do in many situations, which means they won't be as willing to support advantageous decisions for that project, such as extra funding.
- Non-technical people outside of the project won't be as quick to adopt the product, especially when it's an [open-source](legal-ip-floss.md) or [not-for-profit](mgmt-npo.md) project.

## Timing

The more complex the documentation is, the more quickly it will be out-of-date. To that end, there should *always* be a date indicating the last revision of the document.

At the very lowest, review all active documentation at least once a year. Besides checking for errors or updates, also search for ways to consolidate and merge documents, remove obsolete instructions, and relocate documents as needed.

## Forms

One subdivision of technical documentation is forms that users or clients fill in.

- The constraining design of forms is that they are designed as an introductory session to consider having a future event (e.g., government aid, [interviewing](mgmt-3_teams.md)).
- To that end, a form should only be an attempt to gather base-level information, with [a dialogue](people-conversation.md) necessary to gather any further details about a specific situation.

While forms are convenient for gaining information, every single new entry on a form increases the frustration for the user.

- Since the pain is silent (i.e., the form-fillers are suffering it), most [managers](mgmt-npo.md) and [bureaucrats](bureaucracy.md) don't realize the [design](engineering-design.md) risks of adding new requests for information.
- Beyond a specific threshold, the form-fillers will start making mistakes, skipping sections, and may stop finishing the form altogether.

To alleviate the risks of badly designed forms, it's important to review and clean up every form at *least* once every 5-10 years.

## Guides

Generally, there should be several levels of guides:

1. The design-level guide, which gives schematics and details of every single component within the product or process. Since this guide will often possess [trade secrets](legal-ip.md), it should be [secured](safety-security.md) away from the public and only given to authorized individuals.
2. The schematic guide, which gives guidance on how to assemble or create the product or process. This can be publicly distributed among lower-ranking members of the group, but should still be protected to avoid losing trade secrets.
3. The technician guide, which indicates how to [fix](fix.md) the product or [take remedial action](people-customerservice.md). It should either have diagrams for complex elements or indicate where to find them.
4. The user guide, which should have simple instructions and simple pictures. It should be understandable by a moderately intelligent and literate 10-year-old.

## Procedures

There are only a few good reasons to create procedures:

1. Indicate what everyone already knows to save time for new members.
2. Indicate what everyone is doing for the purpose of [staying legally safe](legal-safety.md).

If procedure is created without a clear [purpose](purpose.md), it risks contributing into an [oppressive bureaucracy](bureaucracy.md)

- And, if someone is severely obsessed with *making* a procedure without a clear reason, they may be a [technical idiot](https://gainedin.site/idiot/).

Making procedures involves parsing already-known things into language.

1. Divide out individual activities each worker does into discrete, clear tasks.
2. Sequentially, for each task, explicitly clarify its exact requirements in [writing](language-writing.md).
   - You don't understand it unless you can tell a completely inexperienced teenager *exactly* how to do it.
   - Sometimes, the tasks are different when different roles do them, so clarify those as well.
3. Abstract away all the idiosyncratic details.
   - If the task *requires* precise actions, make it a [rule](rules.md).
   - If it's not critical to perform precisely correctly, make it a guideline (or "best practices").
4. Ask your best workers what they think.
   - Pull them from their work on a slow period.
   - Request for them to show how it's wrong, or if you missed anything.
5. Edit for simplicity.
   - Jargon *can* be useful for specificity, but it slows down the reading and can make the content difficult enough that nobody will read it.
6. Once you have a final draft, publish it with a date attached to it.
7. Routinely (e.g., monthly, yearly), plan a regular review of the entire document.
   - Preferably, have your best workers review the document.
   - Make sure the workers are actually *doing* the procedures.
   - Make sure the procedures in writing are still applicable and sane.
8. Make a new edit for any obsolete or insane instructions.
9. Publicly communicate any divergences from previously stated practices.
   - Before beginning the meeting or message, clarify you will *not* discipline any past-tense violations of the standard.
   - Often, the instructions were either written poorly enough that the workers didn't understand it or difficult to read.
   - End the meeting on good news by telling them what you removed from the instructions as well.
10. Expect [conflicts](people-conflicts.md) and possible re-edits.
    - If people are [accustomed to the old way of doing things](habits.md), and it isn't creating adverse consequences, let them deep doing it.
    - If people don't like the change, clearly and candidly ask them why.
11. Draw extra attention for at least the next few months to divergences from the reviewed tasks from that meeting.
    - Typically, small [changes](people-changes.md) can ripple outward to directly inspiring *other* changes and creating large-scale effects.