A documentation project does not always begin with a blank page.
Sometimes it begins with an existing manual that technically contains information about the product but does not explain it well enough to be useful.
I have worked on assembly documentation where the source material consisted of old, limited instructions and product information that was not sufficient to simply rewrite the document. Before a better instruction could be produced, the product itself had to be understood again.
How are the components related? What is the actual assembly sequence? Which intermediate states or details must the user see to continue correctly?
In some projects, answering those questions meant building a 3D model, reconstructing the assembly logic, deciding which states needed to be shown and only then generating the technical views that would become part of the instruction.
By the time the first final step was written or laid out, many of the most important decisions had already been made.
If the quality of the document depends so heavily on decisions that happen before writing, is technical documentation primarily a writing problem?
I would argue that, in many cases, it is an information-design problem before it is a writing problem.
Writing still matters. So do technical accuracy, terminology and visual quality. But they operate inside an information structure that must first be understood and designed.
Information design begins before layout
Information design in documentation is easy to interpret too narrowly. Typography, page layout, icons, spacing and diagrams all matter, but they are relatively late manifestations of an earlier design process.
Before deciding how information should look, someone has to decide:
- which information belongs in the communication,
- how different pieces of information relate,
- what needs priority or sequence,
- and which form of representation best supports the task.
A visually polished, linguistically correct manual can still be difficult to use. A prerequisite can appear too late. Two variants can be mixed together. An exception can sit outside the flow of a procedure. A diagram can show the correct components from an unhelpful view.
The important distinction is that structure is not the same as formatting. Headings and page hierarchy may express an information structure, but they do not create a sound one by themselves. The underlying work is deciding what belongs together, what depends on what, what should be encountered first and what the user should not have to infer.
In each case, the information may be accurate in isolation while the system around it is poorly designed.
The problem is not simply expression. It is selection, structure, relationships and representation.
You cannot explain a product you do not understand
One of the most important parts of documentation work is also one of the least visible in the finished document: building an accurate understanding of the thing being documented.
Source material is not the same as understanding.
A CAD model describes geometry. A bill of materials identifies components. Engineering notes may describe technical characteristics. A draft manual may contain accumulated knowledge.
None of those automatically produces a usable explanation.
Before information can be designed for a user, someone needs a sufficiently accurate model of how the product works, how its parts relate, what changes between relevant states and what the user is expected to do with it.
This can make documentation work surprisingly investigative.
In another project, the available material included an existing draft, physical devices and 3D models that could be used for visualisation. The devices themselves were tested as part of understanding how they behaved and how that behaviour should be explained.
The job was not merely to convert existing sentences into better ones. Source material had to be compared with the actual product. Behaviour had to be understood. Only then could decisions be made about what needed explaining and how the explanation should work visually.
Documentation, in this sense, can require investigation rather than transcription.
This is also why documentation work often sits between several perspectives on the same product. Engineering may describe construction and constraints; service may be concerned with failure states; product teams may organise information around features or variants. The user encounters none of those departmental boundaries. The explanation still has to resolve them into a coherent model of the product and the task.
The user does not need everything the organisation knows
A manufacturer can possess an enormous amount of information about a product. That does not mean all of it belongs in the user’s path through the documentation.
Many information problems begin when documentation is treated as a container for whatever information is available: specifications are added because engineering has them; an old table survives because it already exists; another paragraph appears because another department asks for it.
The better question is not:
What information do we have about this product?
It is:
What does this user need to know at this point in order to understand the situation or continue correctly?
That is an information-selection problem.
Research context
A study of manual assembly environments at a heavy-vehicle manufacturer found that some information available in work instructions was seldom or never used in practice, while operators also reported issues with information volume, organisation and interpretation in parts of the studied environment (Johansson et al., 2017).
The point is not that unused information is automatically bad. Experienced operators may rely on prior knowledge, while novices may need more guidance. The more useful distinction is between information availability and information usefulness.
Good documentation therefore asks what information is relevant to this audience, in this situation, at this point of need. The same product may require different levels of explanation for a first-time installer, an experienced operator or someone diagnosing a fault. Selection is not simply deletion; it is deciding what belongs in the user’s path and what should remain available elsewhere.
Completeness alone is not the goal.
In procedures, relationships are part of the information
Consider three perfectly clear instructions:
- Insert component A.
- Tighten fastener B.
- Attach component C.
Each sentence can be grammatically correct. Every component can be labelled accurately. And the procedure can still fail.
If component C must be inserted before B is tightened, the problem is not the quality of the sentences. The problem is the relationship between them.
Procedural information contains more than individual instructions. Meaning also exists in sequence, dependency, prerequisites, conditions, branching and verification.
In other words:
The relationship between pieces of information is itself information.
This becomes especially visible in assembly documentation.
A 3D model can represent the finished product accurately while telling the user very little about how to assemble it. Geometry does not determine procedure. Someone still has to establish what happens first, which operations depend on others, what must remain accessible and which intermediate states the user needs to recognise.
Research context
Research on written procedures models step-level complexity in terms that include decision demands, required judgement, interdependencies between instructions, the number of actions and the amount of information a worker must process (Sasangohar et al., 2021).
That research does not mean every dependency automatically makes a procedure difficult. It does reinforce a useful distinction: procedural quality cannot be assessed only at sentence level.
A clear step inside a badly modelled procedure is still part of a badly modelled procedure.
Representation is a design decision
Once the right information and its relationships have been identified, another question appears:
Which representation best supports this particular information problem?
If the user needs to understand spatial orientation, a carefully chosen technical view may do more work than a paragraph. An exact operating limitation may be better expressed in text. A change of physical state may require a sequence of views. A system relationship may be clearer as a diagram.
The useful distinction is not text versus visuals. It is problem versus representation.
That decision is easy to obscure in a production workflow. If text is written first and illustrations are commissioned afterwards, the medium can become an implementation choice rather than part of the reasoning. In practice, some information problems should influence the structure of the explanation before either the sentence or the visual is produced.
Research supports caution against treating one medium as universally superior. In a small-scale assembly experiment, animation produced an initial time advantage over static diagrams and text, but the advantage disappeared after repeated builds (Watson et al., 2010). Separate experiments on one-time mechanical manipulation tasks found that pictures and diagrams could help or hinder depending on the task and the user’s skill level, while well-designed diagrammatic instructions performed strongly in that specific context (Rodriguez, 2001).
Taken together, studies comparing procedural representations do not point to one universally superior medium: performance can vary with the nature of the task, the user and how familiar they have become with the procedure.
The practitioner implication is simpler:
The useful question is not whether information should be visual, but which representation best supports the information problem at hand.
A visual is not automatically useful because it is visual. A 3D view can use the wrong perspective; a diagram can combine too much; an animation can make it difficult to inspect a specific state. Representation still has to be designed.
Good documentation should not make the user reconstruct the system
Another way to evaluate information design is to ask:
What are we unnecessarily asking the user to figure out?
Consider a procedure in which the user has to identify which variant they have, look up a prerequisite in another section, return to the main procedure, infer that an illustration applies only to one configuration and work out an unstated sequence.
All the necessary information may technically exist.
The problem is that the user has to move between locations, remember context and reconstruct relationships that are central to the task. A document can therefore be complete in the sense that nothing is missing and still be difficult to act on.
The communication has transferred much of the integration work to the person using it.
Good information design makes important relationships explicit where it reasonably can. It places prerequisites where they are needed, distinguishes variants clearly, keeps dependent information connected and makes the sequence legible.
The aim is not to explain everything more. It is to avoid making users reconstruct relationships that the documentation could have designed for them.
Documentation is often where upstream problems become visible
Some documentation problems are not created by the documentation process. The process merely exposes them.
While building a manual, you may discover that two sources use different names for the same component, that product variants are represented inconsistently, that a procedure has no agreed sequence, or that a design change is missing from some of the available material.
At that point, rewriting a sentence is not the solution. The underlying information has to be resolved.
Research context
Industrial research provides a useful parallel. Research on assembly information systems shows that problems encountered in work instructions can be connected to wider issues in how information is created, updated, organised and transferred from manufacturing engineering to downstream operations. A 2017 case study explicitly examined gaps between manufacturing engineering and shop-floor use, while a later study broadened the perspective through longitudinal case work and interviews with 17 additional large global manufacturers and three industry experts (Johansson et al., 2017; Johansson et al., 2020).
The studies concern industrial assembly information systems, so the conclusion should remain bounded to that context. But they support a broader practitioner inference:
Documentation can become a place where upstream information problems become visible, even when they did not originate in the document itself.
If producing one accurate instruction repeatedly requires reconciling terminology, variants, source files or product states, improving the final wording may address the symptom without resolving the source of the friction.
This distinction matters because the document is downstream of those decisions. If a variant is defined inconsistently upstream, the documentation team can compensate once. If the same inconsistency continues to enter every new manual, revision or output, the recurring problem is no longer primarily editorial.
A documentation project can therefore act as a diagnostic surface for the information system around a product.
Documentation as an information interface
There is a useful way to bring these ideas together.
Technical documentation can be understood as an information interface between product logic and user action.
A simplified model is:
Product state relevant information user decision action feedback / result
The document is not valuable because it exposes everything known about the product. It is valuable when it translates the relevant part of that product logic into information that helps a user understand what to do next.
This is not an attempt to redefine technical documentation as UX or interaction design. The disciplines are different. The analogy is useful because it shifts attention from the document as an object to the interaction the information enables.
A user rarely opens technical documentation because reading it is the goal. They open it because they need to assemble, configure, operate, diagnose, maintain or understand something. Thinking in terms of an information interface keeps the evaluation anchored to that purpose: does the information help the user move from the current product state to the next correct decision or action?
The document is the visible output
Defining the problem this way changes the questions worth asking early in a documentation project:
- Do we understand the product well enough to explain it?
- What is the user actually trying to accomplish?
- Which relationships and dependencies matter to that task?
- What needs to be shown rather than described?
- Which source is authoritative when information conflicts?
These questions come before many of the decisions that become visible in the finished manual.
The reader sees the final procedure, not the reasoning that established its sequence. They see a technical view, not the alternatives rejected because they hid the important relationship. They see consistent terminology, not the source conflict that had to be resolved upstream.
Technical writing matters. Accuracy matters. Visual communication and editorial quality matter. But they sit within a wider information problem: understanding the product, deciding what the user needs, modelling relationships and choosing how those relationships should be represented.
Before we can write clearly, we need to know what deserves to be communicated. Before we can choose a visual, we need to know what relationship it is supposed to explain. Before we can produce a coherent document, we need a coherent model of the information behind it.
The document is the visible output. The design problem begins earlier.
References
- Johansson, P. E. C., Enofe, M. O., Schwarzkopf, M., Malmsköld, L., Fast-Berglund, Å., & Moestam, L. (2017). Data and Information Handling in Assembly Information Systems – A Current State Analysis. Procedia Manufacturing, 11, 2099–2106.
- Johansson, P. E. C., Malmsköld, L., Fasth Berglund, Å., & Moestam, L. (2020). Challenges of handling assembly information in global manufacturing companies. Journal of Manufacturing Technology Management, 31(5), 955–976.
- Rodriguez, M. A. (2001). Development of Diagrammatic Procedural Instructions for Performing Complex One-Time Tasks. Proceedings of the Human Factors and Ergonomics Society Annual Meeting, 45(7), 687–691.
- Sasangohar, F., Ade, N., Quddus, N., Peres, S. C., & Kannan, P. (2021). Identifying step-level complexity in procedures: Integration of natural language processing into the Complexity Index for Procedures—Step level (CIPS). International Journal of Industrial Ergonomics, 85, 103184.
- Watson, G., Butterfield, J., Curran, R., & Craig, C. (2010). Do dynamic work instructions provide an advantage over static instructions in a small scale assembly task?. Learning and Instruction, 20(1), 84–93.