If you’ve read your phone’s manual or gone through the user guides for a tool you purchased, you’ll notice that the steps and how-tos are straight-to-the-point and are written in a language you understand.
Documentation is part of everyday life; for it to make sense, it must be concise.
Here, I’ll explain what Concise Documentation is and its benefits and walk you through the steps of creating one. Let’s dive in.
Benefits of Concise Documentation
Here are some of the benefits of writing concise documentation:
Simple to consume
A study by the Nielsen Norman Group reveals that most people only read about 20% of words on a web page, and they go further to read if the text is clear, the words and sentences are simple, and the information is easy to understand. This highlights the importance of writing concisely, ensuring the information you are trying to pass is well understood and can be located quickly.
This makes the content appear less intimidating
At first glance, complex documentation overwhelms the reader before they can go through it. Writing concisely breaks down concepts into bite-sized instructions that can be quickly followed.
User-friendly content
Let’s say you’re trying to set up a new piece of software on your computer. You have a manual that’s 50 pages long, with lots of technical jargon and confusing instructions. You’re unsure where to start or how to complete the installation process.
Now imagine you have a concise version of the manual, which has been carefully written to be user-friendly. The instructions are clear and easy to understand, with step-by-step guidance that includes helpful graphics and illustrations.
The concise manual makes the content user-friendly and the software installation process easy without any confusion.
Saves time in navigation
Spending hours trying to find a solution or information in a document can be avoided with concise documentation. The format and structure of concise documentation, like clear headings and subheadings, enable readers to navigate it, saving time and effort.
Steps to Create a Concise Documentation
I’ve talked about the benefits of concise documentation. Now let’s talk about how to write concise documentation. Here are the steps to follow:
Determine your target audience
Who will read this? What information are they looking for? What is their level of technical know-how? Why are they accessing it? These are questions to answer before starting your documentation.
The people using your documentation are your target audience; you must ensure they can easily understand it.
For example, you’re writing a user guide for a new video game. The people who will be using your user guide are the target audience.
To determine your target audience, think about who will be using your documentation and their needs and interests. This can involve doing research, such as looking at demographics or conducting surveys to understand better who your audience is.
By understanding your target audience, you can create documentation tailored to their needs, which is more likely to be effective in helping them understand the information you are presenting.
Use simple language
When creating documentation, it’s important to use simple language so your target audience can easily understand what you’re trying to say. This means using words and phrases that are easy to comprehend and avoiding complicated or technical jargon that might confuse your audience.
For example, if you’re creating a user guide for a new software program, you can use simple language to describe how to perform specific tasks. Instead of using technical terms like “algorithm” or “syntax”, you might use simpler terms like “steps” or “instructions” to make it easier to follow along.
To use simple language, you can write in short sentences and break up long text into small, easy-to-digest chunks.
Keep it simple to navigate
The acronym KISS, which stands for – Keep It Simple Stupid – is a useful reminder to keep things straightforward when creating documentation. It’s good advice to strive for simplicity when communicating complex ideas or information to others.
Keeping your documentation simple to navigate means organizing your content to make it easy for others to find what they’re looking for.
This can be done by:
- Using hyperlinks to help quickly jump to related sections or external resources.
- Adding a Table of Contents or an index so they can locate specific information. This is useful if your documentation is lengthy or covers many topics.
The usability of your documentation needs to be simple to navigate.
Use bullet points
It’s important to make your documentation easy to follow through. This can be done by using a bullet point.
Bullet points are small, circular symbols that precede each item in a list. They are a great way to present information in a concise and organized manner.
Here are some reasons why bullet points are useful:
- They help to prioritize information: You can use bullet points to highlight important information or to create a hierarchy of information. This helps your readers to understand the relative importance of each item on your list.
- They break up long paragraphs: Large blocks of text can be daunting and difficult to read. By using bullet points, you can break up long paragraphs into smaller, more manageable pieces.
- They make information easy to scan: Bullet points allow readers to quickly and easily scan your content to find the necessary information.
When using bullet points, it’s important to keep them short and to the point. Each point should be brief and easy to understand.
Include a tree structure (headings and subheadings)
A tree structure organizes information into a hierarchical or branching structure, similar to a tree with a main trunk with many branches. In documentation or writing, this means breaking down the content into main sections or headings and then further dividing those sections into subheadings or subsections.
For example, let’s say you’re creating a document about different types of animals. You might use a heading like “Mammals” to group together information about animals that have fur and nurse their young. Underneath the “Mammals” heading, you could use subheadings like “Cats,” “Dogs,” and “Horses” to further organize the information.
Using a tree structure helps to break up the text into manageable chunks so that people don’t get overwhelmed by a big block of writing.
Consider how to break it down into different sections using headings and subheadings.
Make use of illustrations and graphics
When explaining something complex or technical, use pictures or diagrams to show what you mean. That’s where illustrations and graphics come in!
Illustrations are drawings or pictures that help to explain a concept or idea. Graphics are visual representations of data, such as charts or graphs, that show information in a way that’s easy to understand.
For example, suppose you were creating a user manual for a new computer game. In that case, include illustrations of the game’s interface to show the player where different buttons and options are located. You could also include graphics that show the player’s progress through the game or their score.
By using illustrations and graphics, you can make your documentation more engaging and easier to understand. Visual aids help break up the text and make it less intimidating, encouraging people to read and engage with your documentation.
It can also help to make your documentation more accessible to people who learn better through visual aids.
If you’re creating your illustrations or graphics, many tools available online can help you create professional-looking images. You can also find free images online that you can use in your documentation. Just credit the original creator and check that you have permission to use the image.
Conduct a peer review
As you work on your documentation, it’s crucial to have someone else review your writing to ensure it’s concise. This is where peer review comes in – it involves asking someone you trust, like a friend or coworker, to read through what you’ve written and give you suggestions on how to improve it.
The reviewer can provide feedback on various aspects, such as:
- The clarity and coherence of your writing.
- Any errors or typos that need to be corrected.
- If your writing is appropriately tailored for your intended audience.
Once you’ve received feedback from your peer reviewer, you can use their suggestions to improve your writing.
When you conduct a peer review, it’s important to choose someone you trust to give you honest feedback and who knows the subject you’re writing about. You can also return the favor by offering to review their writing in exchange!
Top comments (0)