In the beginning, there was chaos: entities of an extremely intricate and complex nature with just rudimentary shapes and forms, making it impossible to give them a name or identify exactly how they fit together. With time, the features and characteristics of certain entities could be distinguished and the relationship of these entities to and interaction with similar entities became clearer. Evolution? No, just an excerpt from the information development process.
documentation is a necessary product deliverable, but is often labelled as a necessary evil
In technical communication, documentation plays a major role because it is a necessary product deliverable. Technical documentation comes in many forms:
- manuals for administration, installation, operation, and service
- product descriptions (technical specifications, system requirements, operating conditions)
- user guides (how-to guides and quick-reference guides)
- user interfaces (menu, navigation, and dialog labels, mouse-over text)
- training material
when users are looking for answers, reading the product documentation is often not their first course of action
Yet when we need a piece of information to solve a tricky problem, there is often not enough time to read through volumes of technical documentation (AKA “I have a deadline on Friday.” or “I need to leave at five today.”). Invariably, we try to find the answer through investigation (AKA trial and error or learning-by-doing) or we ask someone else for help and advice (AKA “Have you got a minute?” or “Can you do me a favor?”). After all, reading is not the only way to obtain information.
One online dictionary defines information as:
knowledge obtained from investigation, study, or instruction
documentation is often the last resort because users cannot find the information they need
So what do we do when trial produces more errors than we have time to solve or no one has a spare minute? How do we obtain the knowledge we require? We are forced to read through the product documentation. But sometimes, no matter how much written information is available, the answer is just not to be found. The reason for this often lies in the “raw” nature of written content. This is where information development comes in.
technical writers turn raw information into meaningful content
Information developers (AKA technical writers) take raw content in the form of technical specifications and product design documents, interview software developers and engineers for more information, and try out the products themselves. Using the knowledge they have gained through investigation, study, and instruction (raw input), they then develop a meaningful structure with the ultimate goal of developing a polished deliverable (functional output).
good documentation focuses on user requirements
Deliverables may be intended for printed publication (frequently “print” no longer means “printed”, but a linear representation of documentation as a PDF) or online distribution (Windows help, HTML help, Web pages). Irrespective of the output medium, all documentation must be developed to serve the purpose of the intended readers. The main purposes of documentation are:
- information (to gain an overview)
- action (to perform a procedure)
- instruction (to learn how to do something)
- decision-making (to choose the best solution)
Furthermore, content must be written in an appropriate style that is clear, concise, and comprehensive. Ideally, readers should be able to skim-read a text and be able to identify the information they seek within seconds. At the end of the information development process, it is likely that the raw input and the functional output will bear no resemblance; however, the information – the essential message – should be the same.