Everyone hopes that they will never need assistance when using a product. But, sometimes we need to look for detailed information or follow a guide to make sure we are doing it right. The problem is, you don’t want to search through pages and pages of documentation...You want to find your answer quickly and easily.
This is why Technical Writers are so important. Their job is to provide you with useful information, as if an expert was walking you through each step, regardless of your expertise level, language or culture.
Not only should Technical Writers provide customers with the right information, but also write it in an engaging way to make you want to open the Manual and read it again.
What matters most is that writers create high quality documentation. It must be standardized and written in a minimalist way to fulfill the needs of users.
Good Documentation is Standardized
Several Technical Writing standards have been established in the past decade. The most common guidelines used across all Industries around the world is DITA (Darwin Information Typing Architecture). IBM created DITA about ten years ago to standardize its’ software documentation. It is based on XML architecture, with very specific tags related to procedural and textual matters.
Without going too deeply into details, DITA allows Technical Writers to categorize the information into three types of “topic" sections (similar to chapters).
- Tasks (the core topic type) are for procedures. Procedures are composed of prerequisites, steps, results and sometimes post requisites.
- Concepts is the section where conceptual information is placed. It includes definitions of features, concepts for beginners and all theoretical information.
- References are referential material containers. Reference topics are used for lists of terms, icons descriptions, keyboard shortcuts, tables of definitions, etc.
For example, a step element is not valid in a Concept topic, because it belongs to the Task topic section. This is where DITA writers become Information Architects. Topics are like bricks of information that, once put together, have to form a solid Content structure like a wall.
DITA is XML, thus the content is completely separated from layout. The layout is managed by stylesheets, allowing it to generate content either for printing purposes, web output, CHM files, portable devices, etc...All from the very same source of content. That's called single-sourcing:
So why do this instead of writing 600 pages of information?
Chunking the information into small parts makes it easier to maintain. Then, only a small file will need to be edited (and translated) when a modification is made. It’s also beneficial because the documentation can be published again in several formats.
When authors follow rules and guidelines for each element of content, the potential for reusing the information is greatly enhanced and the consistency will be dramatically improved. This is called predictability (Technical Writing lingo). Predictability is the direct result of consistency. When information is presented and structured in a consistent way, users will become used to the patterns and structures they see. They will find the information faster and understand it easier because they will be able to “predict” where to find what.
Too much content can be worse than not enough content
When we are looking for information, we want to find it immediately. Otherwise, we’ll probably never open the User Manual again.
In Technical Communication, minimalism helps improve the documentation quality. It’s not necessary to have hundreds of pages of details...No one will ever read it. Rather, the key is to focus on providing information users need: procedures for experts with a touch of conceptual information for beginners, but always remaining task-oriented. Our customer’s work doesn't break down into chapters, because they are...tasks.
It’s time for me to follow my own rules and stop, not to confuse you with too much information. We have now covered the main cornerstones of a Technical Communicator’s job: standardization, information reuse, task-oriented content, minimalism and single-sourcing.
Because our customers matter, Technical Documentation matters.
Are you a beginner at Technical Writing? Do you find DITA to be very useful? Let us know about your experience with Technical Documentation! If you have any questions, feel free to leave me a comment and I'll get back to you soon.