Five Quick Tips for Writing a User Manual
Hey everyone!
This is gonna be a super quick post on 5 quick tips, especially for SMEs and beginners who wish to get started with producing user manuals for software products. All these tips are some of the basics I’ve learned through the first few months as a Technical Writer and hope you find them useful.
1. Think like the user
As simple as it may sound, it’s the most difficult thing to do given that you are an SME. But to produce user-friendly content, you need to put on the “user’s hat” and think like a user. 🎩
Since you have a great understanding of how the users interact with the software, make the most of that experience and note down what they need to do and how to get started and.
Do not use the term “user” in the documentation and use you instead.
2. Active voice for simplicity
Always try to use active voice. The sentences are more concise and clear.
The structure is simpler because the word count is low. This will help the users to understand the message easily. Also, an active sentence sounds stronger, so it will be more likely taken seriously.
Don’t: A certificate is issued by a trusted organization. ❌
Do: A trusted organization issues a certificate. ✅
3. Punctuation for clarity
Punctuation provides the important clues that help your reader to understand your writing. They add clarity and accuracy to writing. You can ask the readers to stop, pause, or give emphasis to certain parts of the sentence.
- Formatting punctuation in the text describing interaction with the UI, parentheses, and brackets.
In the APIs tab, select CREATE NEW API > I Have an Existing REST API.
Notice how all UI labels are bolded.
Open the <APIM_HOME>/repository/conf/deployment.toml file.
The file path is formatted so that it stands out from the rest.
2. Commas in series, clauses, and dates.
- Oxford comma/Serial comma — Use a comma before the conjunction in a list of three or more items.
It ensures the online transactions, online account access, and other online actions are more secured.
- Following an introductory phase
Unlike the previous versions, now we have to configure a single toml file to configure each component.
- To join two independent clauses
Download the non-OSGi jar for the required third party product, and save it in a preferred directory in your machine.
4. Lists 📝
You can use lists to explain a complex set of information/instructions in an easy to scan manner. Always make sure the list items are comparatively shorter.
Make items in a list parallel. For example, each item should be a noun or a phrase that starts with a verb.
- Bulleted lists
Use them to list something that doesn’t necessarily need to happen in a particular order.
- Numbered lists
Use a numbered list for sequential items. The reader needs to follow the order.
1. Go to the Main tab on the left top corner, and select Identity -> Users and Roles -> Add.
2. Click Add New Role.
3. Create the following user roles:
5. Structuring your content
At times, the volume of content can be exhausting. As a writer, you need to help your reader find what they are looking for.
Proper organization of content into separate paragraphs/sections will add clarity to the overall documentation. It also makes the content scannable for the readers.
- Headings: using proper headers/titles and supporting paragraphs.
- Lists: Use lists whenever appropriate.
- Tables: Another great way to present information.
A writing style guide can help you stick to a standard when producing content. Check out the Microsoft Style Guide that contains awesome tips to improve your writing by adhering to MS Style.
Happy Writing! ✏️✨
