Technical writing is an important building block within any community, especially when advocating for a product. Documentation is the first direct contact you have with developers and users interested in getting to know and using the product.
The better the writing the better the odds of them coming back and getting involved with the community. But, what exactly is technical writing?
Technical writing is designed to make hard concepts as easy as possible for the readers. It’s more common than you think, whenever you read a user guide, a tutorial, case studies and many others are common examples of technical writing in the field. It is designed to explain specialised information to those that are not familiar with it and help those that are deepening their knowledge.
It’s important to notice that technical writing and documentation have their differences but keep in mind good documentation practices can help enrich your technical writing. Developer documentation is essential for technically communicating with users, now knowing how important it is, we can identify some common mistakes and we can avoid them when making our documentation.
Common mistakes
Assuming the reader has the same technical knowledge as you: By thinking this way you are limiting the number of users and developers that are going to interact with your product. This is why it is important to know your audience. You should always explain based on the different levels of background education your readers will have, not the ones you possess.
Not disclosing acronyms: You should always write in the text the meaning of the acronym before actively using it in your documentation enclosed in parenthesis. This is heavily tied to the previous point, don’t assume the reader has the same technical knowledge as the writer.
Using passive voice: This leads to less clarity and ambiguity. Using an active voice will urge the reader to take action and understand the document they are reading more clearly because it keeps sentences from becoming too wordy.
Skip minor steps: By skipping minor steps that the writer thinks are a given, the reader will be lost and won’t know what to do. Do not skip steps when the goal is to make the user complete a task or understand a concept.
What makes documentation good?
Good documentation is meant to explain to your audience heavy concepts in an easy way. It is a lightweight task with no direct flow of income but it's necessary. This is why documentation is often overlooked, but in the long run, the benefits are palpable. It helps not only instruct your user but to document the development process.
Here are some ways you can improve your documentation:
Write in simple terms: There is no need to use extremely technical terms when writing. The safe option is to write simply about what to do and a quick overview of the why. Think of a way to deliver the content in a way that’s easy for readers to understand whether or not they have prior experience with the product.
Have a style guide: It can help create a consistent voice within the company, the reader will respond to a standardized form of content, terminology and visuals. There is no need to start from zero, there are many documentations that can serve as a guide.
Get community feedback: This way you can get immediate feedback from the community on the guides that are working and those that are confusing.
Track changes: Have a version control that will help you track changes over time, in case a new feature is later removed because of the user’s reaction, you can revert back to the previous documentation.
Think about the users reading your documentation: Is your documentation accessible? Is it easy to follow? Can they easily find what they were looking for?. Help users have a frictionless interaction with your documentation.
Inclusivity and Accessibility: Avoid idioms to help cater to your international audience, consider people using screen readers, make sure you have a good contrast ratio in the design, and if you make use of screenshots make sure they have text.
Which audience should you focus on?
Depending on the type of audience your goal is you should adapt your writing to fit the audience's needs. We can identify two different target audiences with their different needs that need to be fulfilled, developers and users.
Developers
Developers play an active role when reading documentation, having clear guides in place will make them want to contribute and help with the product, making the code, documentation and community better. They have a way more different approach on documentation than users do, so let’s see what types of documentation they focus on:
Types:
API documentation: It serves as a reference on everything regarding API calls.
Read Me’s: It is meant to be an overview of the product, usually with the source code.
System documentation: The goal is to describe the product, technical design documents, software requirements and more.
Release notes: It shows information about releases, bug fixes or the latest version.
Users
They can play both an active and passive role when reading the documentation. They want to use your product, and an active voice should be used when talking to them. Some ways of targeting the users are writing easy-to-follow guides and adding code snippets and external sources when needed to expand the information. Some of the types of documentation they focus more on are:
Types:
How-to guides: It takes the user through a step-by-step detailed process to help them reach a goal. It is problem-oriented. It helps the user complete a task.
Tutorials: The goal is to leave the user with knowledge of a concept or process. It’s meant to provide a successful learning experience.
Explanations: They’re written to help users clarify certain topics that users might not have knowledge on.
Reference docs: Are made to share with the user more technical descriptions of the product.
It is important to find a good balance between the developers and the users. Both should be targeted in different ways all throughout the documentation. When making user-focused documents you should use less technical lingo than when targeting the document to developers, taking into count their background and experience and the different types of content they focus on.
Closing thoughts
Documentation is changing the way developers and users interact with products, good documentation motivates people to be active within the community, and it creates loyalty to the product and a sense of unity. This is why documentation shouldn’t be an afterthought, good documentation can make or break your product and community.
Thank you so much for reading!
Comments