Arranging Information in a Structured Way¶
Organization of the information plays a vital role in effective communication of technical content. If the user feels the information is important to them, they may try to read the document once, even if it’s poorly written. But, if it’s poorly organized, they will never read it.
Arranging information in a structured way helps to form a coherent arrangement of parts that makes sense to the user. It applies both to the arrangement of information within a topic and to the arrangement of two or more topics (how topics fit together).
Let us see how we can arrange the information in a structured way that will help the user makes sense of the information:
Stand in the Users’ shoes¶
How do you structure your writing according to the way your user thinks about the subject?
By putting yourself in their shoes and asking, What about this subject concerns my users most and would gain their interest?
Write information only when you understand it, and then verify it. Keep up with technical changes. Maintain consistency of all information about a subject.
Outline a document¶
Starting with a structured, high-level outline can help you group topics and determine where more detail is needed. The outline helps you move topics around before you get down to writing.
You might find it useful to think of an outline as the narrative for your document.
Introduce a document¶
If readers of your documentation can’t find relevance in the subject, they are likely to ignore it. To set the ground rules for your users, we recommend providing an introduction that includes the following information:
- What the document covers.
- What prior knowledge do you expect readers to have.
- What the document doesn’t cover.
Remember that you want to keep your documentation easy to maintain, so don’t try to cover everything in the introduction.
Proper segregation of topics¶
In technical writing, the topic can be mainly categorized into three types:
- Task
- Concept
- Reference
Structuring your information into these discrete topics gives you the flexibility to reuse the information or any portion of it for a variety of presentations. In addition, topics are generally short and therefore more searchable and more likely to provide users with just the information that they need.
Complete coverage of topics¶
Cover all topics that support users’ tasks and only those topics. Cover each topic in just as much detail as users need to complete the task. Avoid extraneous details in the task-oriented information. Use patterns of information to ensure proper coverage. Repeat information only when users will benefit from it.
Follow chronological order¶
Arrange the information in chronological order, so that the user can relate to the information. Start with simple examples and instructions, and add progressively more interesting and complicated techniques. For example, in a tutorial for creating forms, start by explaining how to handle text responses, and then introduce other techniques to handle multiple choice, images, and other response types.
Proper table of content¶
Helping readers navigate through your documentation helps them find the information they need to successfully use your tool. Often, a clear and well-organized table of contents or outline acts like a map that helps your users navigate the functionality of your tool.
Follow parallelism in information¶
One way to help users understand information the first time that they read it is to present similar information similarly. This guideline applies to both the content and the format of technical information.
Follow template designs¶
Using the same template across sets of information, such as for related products, ensures that the information maintains a consistent structure and appearance.
Follow style guidelines¶
Style guidelines can specify what text to highlight, what tone to use, or what spellings to use. Style guidelines help ensure that writers working on related information do not introduce variations that will create an inconsistent presentation.
Present list items consistently¶
Use a complete sentence for the list lead-in sentence unless your style guide specifies that you should use fragments. Include at least two items in a list.