The user who reads the doc Writing good documentation for any piece of software is not an easy task. There are many things you should keep in mind when doing your everyday work. All of them, and your skill and effort as well, shape your text into a highly usable piece of documentation. Let’s discuss the first thing to consider when starting your task: The User. Also well-known as “the Client”, the User is a human being, who represents the target group. The target group will use the documentation in their everyday work to find out how to use the piece of software to fulfill their professional needs. The documentation should look like helpful advice provided by an experienced friendly professional – this is the popular requirement from corporate style guides. To address it, you have to completely understand who reads the documentation and why. To achieve that understanding, find answers to basic questions (product and engineering teams may help you with this). Let’s go through these questions. What is the software and how is it used? This information shows you: The set of tasks the User might want to do.


The exact amount of information they need to use the software. Also, as you learn the software, you will find the problems, the complex parts and other sources of trouble for the client which can be fixed or covered in the doc. Remember, nobody reads the doc as a book. All articles and instructions are mainly used to find how to achieve the result they need. How skilled is the user? This is one of the most important questions. Undoubtedly, each user in the target group has slightly different skill levels. You should communicate with the user at their level of understanding, as this allows you to give the details and drastically reduce the amount of unused text (which is skipped by the user who wouldn’t read the information they already know). The mistakes here: Aiming the text at a less experienced user. In this case, the real user has to skip a lot of information just to find out that the information they were searching for is missing as it was too complicated.


Making the text too complicated for the User. In this case, the User has to learn a lot more than they need to perform the task. The text is rich in unnecessary details. These mistakes will result in Users asking technical support for help instead of quickly finding the required information on their own. What is their profession? This information will help you to: Tune the text to make the document comfortable for the user.


Limit the excessive definitions and descriptions of the basic terms. Remember, the documentation should look like helpful advice provided by an experienced friendly professional. This means the technical writer should completely understand the field of professional knowledge where the software (and the User) belongs. Many abbreviations, terms, and concepts are well-known for professionals with similar backgrounds. Use the existing basis to build communication with your reader. Slang: yes or no? Ideally, Users do not need to tune their knowledge to your documentation – the documentation tunes to the Users. Sometimes, the professional slang may be the best way to achieve this. Note: most style guides forbid using slang words. This is a great idea in general, but sometimes, especially if you write the text describing a really specific feature or if you are aiming to describe something for a very specific audience (for example, cybersecurity specialists or electronic engineers) it is much easier to use a well-known slang word instead of creating a new word that nobody knows. Be mindful when wiping out all slang words according to the requirements of the style guide. What is their Role? Sometimes Users with the same background use the software with different roles and access levels. It is very useful to figure out: What roles/access levels exist in the system?


How do these roles/access levels affect the work patterns of the User? The role (or access level) determines the set of functions available to the user. Actually, this is a really important part of describing your User: if the software has some role-based access, this means that certain functions are available only to certain Users. This will directly affect the volume of your documentation, its structure and also the language and focus for each role. Make sure you investigate the roles/access levels when creating a new piece of text, as ignoring it may even violate security policies. Summary Now, you have a portrait of somebody who will read your documentation. This information lets you to precisely address all user questions and needs in your documentation and make it highly usable. To sum up: Know the software.
Know your reader.
Be mindful when using style guides and other limitations.
Get familiar with the roles and access permissions available for the user. The user who reads the doc Writing good documentation for any piece of software is not an easy task. There are many things you should keep in mind when doing your everyday work. All of them, and your skill and effort as well, shape your text into a highly usable piece of documentation. Let’s discuss the first thing to consider when starting your task: The User. Also well-known as “the Client”, the User is a human being, who represents the target group. The target group will use the documentation in their everyday work to find out how to use the piece of software to fulfill their professional needs. The documentation should look like helpful advice provided by an experienced friendly professional – this is the popular requirement from corporate style guides. To address it, you have to completely understand who reads the documentation and why. To achieve that understanding, find answers to basic questions (product and engineering teams may help you with this). Let’s go through these questions. What is the software and how is it used? This information shows you: This information shows you: The set of tasks the User might want to do. The exact amount of information they need to use the software. The set of tasks the User might want to do. The set of tasks the User might want to do. The exact amount of information they need to use the software. The exact amount of information they need to use the software. Also, as you learn the software, you will find the problems, the complex parts and other sources of trouble for the client which can be fixed or covered in the doc. Remember, nobody reads the doc as a book. All articles and instructions are mainly used to find how to achieve the result they need. How skilled is the user? This is one of the most important questions. Undoubtedly, each user in the target group has slightly different skill levels. You should communicate with the user at their level of understanding, as this allows you to give the details and drastically reduce the amount of unused text (which is skipped by the user who wouldn’t read the information they already know). The mistakes here: Aiming the text at a less experienced user. In this case, the real user has to skip a lot of information just to find out that the information they were searching for is missing as it was too complicated. Making the text too complicated for the User. In this case, the User has to learn a lot more than they need to perform the task. The text is rich in unnecessary details. Aiming the text at a less experienced user. In this case, the real user has to skip a lot of information just to find out that the information they were searching for is missing as it was too complicated. Aiming the text at a less experienced user. In this case, the real user has to skip a lot of information just to find out that the information they were searching for is missing as it was too complicated. Making the text too complicated for the User. In this case, the User has to learn a lot more than they need to perform the task. The text is rich in unnecessary details. Making the text too complicated for the User. In this case, the User has to learn a lot more than they need to perform the task. The text is rich in unnecessary details. These mistakes will result in Users asking technical support for help instead of quickly finding the required information on their own. What is their profession? This information will help you to: Tune the text to make the document comfortable for the user. Limit the excessive definitions and descriptions of the basic terms. Tune the text to make the document comfortable for the user. Tune the text to make the document comfortable for the user. Limit the excessive definitions and descriptions of the basic terms. Limit the excessive definitions and descriptions of the basic terms. Remember, the documentation should look like helpful advice provided by an experienced friendly professional. This means the technical writer should completely understand the field of professional knowledge where the software (and the User) belongs. Many abbreviations, terms, and concepts are well-known for professionals with similar backgrounds. Use the existing basis to build communication with your reader. Slang: yes or no? Ideally, Users do not need to tune their knowledge to your documentation – the documentation tunes to the Users. Sometimes, the professional slang may be the best way to achieve this. Note: most style guides forbid using slang words. This is a great idea in general, but sometimes, especially if you write the text describing a really specific feature or if you are aiming to describe something for a very specific audience (for example, cybersecurity specialists or electronic engineers) it is much easier to use a well-known slang word instead of creating a new word that nobody knows. Be mindful when wiping out all slang words according to the requirements of the style guide. Note: most style guides forbid using slang words. This is a great idea in general, but sometimes, especially if you write the text describing a really specific feature or if you are aiming to describe something for a very specific audience (for example, cybersecurity specialists or electronic engineers) it is much easier to use a well-known slang word instead of creating a new word that nobody knows. Be mindful when wiping out all slang words according to the requirements of the style guide. Note: What is their Role? Sometimes Users with the same background use the software with different roles and access levels. It is very useful to figure out: What roles/access levels exist in the system? How do these roles/access levels affect the work patterns of the User? What roles/access levels exist in the system? What roles/access levels exist in the system? How do these roles/access levels affect the work patterns of the User? How do these roles/access levels affect the work patterns of the User? The role (or access level) determines the set of functions available to the user. Actually, this is a really important part of describing your User: if the software has some role-based access, this means that certain functions are available only to certain Users. This will directly affect the volume of your documentation, its structure and also the language and focus for each role. Make sure you investigate the roles/access levels when creating a new piece of text, as ignoring it may even violate security policies. Summary Now, you have a portrait of somebody who will read your documentation. This information lets you to precisely address all user questions and needs in your documentation and make it highly usable. To sum up: Know the software. Know your reader. Be mindful when using style guides and other limitations. Get familiar with the roles and access permissions available for the user. Know the software. Know your reader. Be mindful when using style guides and other limitations. Get familiar with the roles and access permissions available for the user.

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Style Guide in a Nutshell: What to Know

Read My Stories

Too Long; Didn't Read

Make resilience your competitive advantage

Mastering User-Centric Software Documentation

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

How to Onboard a New Technical Writer

5 Software Documentation Tools That Make Managing Technical Documentation Easier

6 Surefire Ways To Suck At Maintaining Projects

62 Stories To Learn About Documentation

An Easy README Makeover In 3 Simple Steps

How to Onboard a New Technical Writer

5 Software Documentation Tools That Make Managing Technical Documentation Easier

6 Surefire Ways To Suck At Maintaining Projects

62 Stories To Learn About Documentation

An Easy README Makeover In 3 Simple Steps

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps