We follow an online Documentation Philosophy: “Every page can be page one”.
When transferring an offline manual to an online manual, a one-to-one copy will not suffice. This is due to the nature of online documentation and the way in which online documentation is read.
Ensure Structure
Some readers may still want to read through a document in a traditional way, i.e., sequentially from beginning to end. Thus, a proper structure in terms of categories (replacing the traditional chapters in the offline version) remains important. In addition, the structure is also crucial for the editors. They need this to keep things organized and maintain an overview.
Create Context
With online documentation, most readers would rather do a search on a specific topic. The relevant articles will then be represented to them, and they will click on a hyperlink to navigate to one of the listed articles. The headings of the articles play an important role in helping the reader find the correct article. A heading should already place the article in context and explain what it is about. However, the heading cannot always create enough context. Therefore, the first paragraph should also be used to explain where in the bigger picture the article fits in. Showing a picture (flow chart) in the beginning can also help orientate the reader. In addition, Tags and related articles should also be used to help create the context. The idea is that every article could potentially be the first article that a reader lands on. Therefore, every article should have enough context to orientate a reader in terms of the bigger picture.
Avoid Duplication
To ensure consistency, any content duplication should be avoided in the IMS Handbook. In other words, if content is relevant to an article, but already covered somewhere else in the IMS Handbook, the content should not be duplicated in the second article, but rather a link should be added to direct the reader to the article where the original content is covered. Also adding related articles can help to avoid content duplication.
Uniform Style
Lastly, to ensure the whole IMS Handbook has a uniform feeling, we should aim to style and organize all articles in a consistent manner. Although a lot of the style is already built into the Document360 knowledge base, and can be specified in the background, not everything can be automated. The below procedure therefore also aims to ensure that the remaining items follow a consistent style in terms of colors, pictures, tables, etc.
For more information on the symbols we use in the IMS Handbook, refer to the Symbols Guide.
For more information on writing style, appropriate IT terminology, or best practices when writing about computer technology, refer to the Microsoft Writing Style Guide. Use the search box in the left-hand pane to look for topics of interest.
Tone of Voice
Address the readers directly, rather than in the first person. This ensures better engagement. For example, do not write "the user should see...", but rather "you should see...".
Principles of Minimalism
Follow the Principles of Minimalism where possible. For instructions, give short bulleted actions.
To learn more about Principles of Minimalism you can listen to this podcast: Using the Principles of Minimalism to Create Better User Support, with Dr. Hans van der Meij
The four principles are:
Adopt a user‑centered approach
Provide support to help people perform a task. Brevity is the result of being use‑ and user‑centered. You have to assume that users can already do certain things in order not to repeat information they already know. Typically, we're writing for professionals, whether they're novices or experts in their fields
Focus on meaningful, task‑oriented instruction
When you teach a software task, it has to have meaning for the person’s work. Teach people software functionality in the context of their job.
Support error handling
Support people in handling errors. This means preventing errors where possible and helping users manage errors when they occur. You should support error detection and correction. In some cases, you may also support basic problem diagnosis. This is one of the few moments in minimalism where you provide more information than users may immediately need. This can feel counter‑intuitive for brevity, but it actually saves users time.
Ensure easy access to information
This principle focuses on structure and findability. Use good headings, a clear structure, and a table of contents to help users find what they need quickly. This builds on information‑mapping principles, where key information is presented in its own place and in a consistent way. Once users understand the structure, they can easily skip or find relevant information when needed.