All technology, proportional to the details necessary to operate or service it, requires some form of written language to indicate how to use it.
Technical documents only come from a few possible types of people:
- The designer wanted to make life easier for their product’s users and maintainers.
- The maintainers wanted to make life easier for the users after fixing something.
- 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:
- How bad things will get if the thing stops working.
- The scarcity of alternative approaches that don’t use that particular piece of technology.
Whenever the design of the interface/hardware 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 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 and decision-making 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 project.
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).
- To that end, a form should only be an attempt to gather base-level information, with a dialogue 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 and bureaucrats don’t realize the design risks of adding new requests for information.
- Beyond a specific threshold, the form-fillers will start making mistakes, skipping sections, and may drop out of 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.