Technical Writing Best Practices
We all know technical writing best practices like:
- Use the active voice.
- Avoid fancy words.
- Follow grammar rules.
- Use visual content to clarify concepts.
If you’re a novice in technical writing, you can find more information here: Tips on Improving Technical Writing.
Today I’ll talk about some advanced best practices.
Add Getting Started Topic
Create a quick reference chapter, section, or guide — it will be helpful for users, especially the new ones. A quick reference helps readers get started and they will not have to comprehend a large amount of information beforehand.
Here is an example. ClickHelp provides users with the Getting Started topic where you can learn what ClickHelp is, its features, possibilities, and online help topics.
Moreover, if you create a project from a template, you’ll also see the quick reference topic that will help you learn ClickHelp better.
However, you should keep in mind that, probably, experienced users don’t need such a topic. In order to hide it, use output tags (if you use a professional software documentation tool). They help to create different versions of your document. You can learn more about output tags and how I use them here: ‘How to Organize Documentation’.
Create Step/Action Table
Usually, steps in documentation look like this — just a numbered list of the information where screenshots feature the steps:
I think a step/action table will be more useful in some situations than just a list.
A step/action table usually provides users with more background information than an ordinary list. Procedures contained in a table are easy to read and follow that increase document effectiveness. A step/action table breaks a task into step-by-step instructions that’s why a reader can easily follow to achieve a specified outcome.
Use Context Help
Context-sensitive help is a kind of online help that is obtained from a specific point in the state of the software, providing help for the situation that is associated with that state. It can be provided in different forms like links, popup windows, assistant panels and so on.
Context Help as a Popup Window — Source
Context Help helps to make your app user-oriented and easy to handle — a user can just click the link and get the necessary information, so the difficulties users might face can be solved quickly.
Check Your Understanding Topic
How to gather information on whether your topics are readable or not? You can use analytics if your HAT supports it. For example, ClickHelp provides users with its internal analytics that helps to monitor your readers behavior.
Otherwise, you can create “check your understanding” topic as Apple did — SwiftUI Essentials, Creating and Combining Views.
It helps both technical writers and readers. Technical writers can gather the information and examine what questions are the hardest ones, so it will be a signal that they should rewrite the relevant topics. At the same time, readers will be more serious about your documentation, and the questions will help them sum up the information. So, everybody wins.
README file
If you need to write a README file, Franck Abgrall created a readme generator. Readme-md-generator is able to read your environment (package.json, git config…) to suggest you default answers during the README.md creation process:
Make sure you have npx installed. More details on usage here.
What are your advanced best practices for technical writing?
