This faux pas taught me that I need to look at our product through the prism of the customer. Then the proverbial light switch clicked "on." If I deliver a product that addresses the customer's pain points, then support it with professional product documentation, we will have a winner.
And I also discovered creating professional, aesthetically pleasing, and easy-to-read product documentation was not an easy task. But when done correctly, product documentation can make happy customers ecstatic and ultimately increase revenues.
What Are the Best Practices for Creating Professional Product Documentation?
These best practices create aesthetically pleasing, informative, and easy-to-use product documentation. Following these guidelines will help you deliver product documentation that can make a good customer into a great customer. And great customers ultimately help companies increase revenues, with product documentation being a vital component of the customer experience.
1. Understand your target audience and give them what they want
It is essential to know what your audience's expectations are. For example, is the product documentation intended for Administrators or End Users? The scope of your target audience may require writing technically for Administrators or in clearly defined terms and instructions for the End User.
A best practice for creating professional product documentation is understanding customer expectations at the Administrator or End User level. Some of the methods to collect identifying audience information are:
-
Questionnaires and Surveys
-
Perceived audience feedback
-
Company brainstorming
-
Feedback on popular customer opinions
-
Customer roundtable discussions
2. Create a documentation plan as a best practice
Writing a documentation plan can help vision any potential bottlenecks during the project implementation. Creating product documentation can be challenging, and a best practice is to create a documentation plan to help foresee issues that can pop up during the documentation process.
Among the benefits of creating a documentation plan are the following:
-
Actionable items - Auditing any existing documentation to salvage applicable information that can be reused with the new product documentation plan.
-
Observe templates and style guides - If the product documentation is for a new product, make sure it stays within the voice and style of the industry, or if the documentation pertains to an existing product, maintain the current style guides and templates to ensure the continuity of the brand.
-
Document process tooling - Document tooling can define and streamline the product documentation process while ensuring teamwork continuity and a better understanding of the document development process.
3. Simplify product documentation as a best practice
A study was conducted in 2016 to determine how many users read the product documentation. The results were eye-opening as they discovered only 25% of users do not read the product documentation. The survey found the lack of end users not reading product documentation is in part due to the following:
-
Users are impatient - With the advent of immediate information via the web, users typically become less patient in discovering answers to their problems. Reading product documentation online or offline can be laborious due to the copious amounts of information required for a particular product.
-
Skip-ahead syndrome - Users often skip over necessary product documentation straight to the basics of how to use the product. Users learn and understand how products work through interaction with the product rather than reading detailed instructions. Instructions must be as clear and informative as possible.
-
Confusing layout and structure - Manuals are often written in a format that is difficult to understand and follow. Many users find the product documentation confusing or irrelevant to their question, becoming frustrated and discouraged from reading the manual. Often, the company did not conduct detailed audience research and not correctly understand what the user needed, and became too confused to finish reading.
4. Include screenshots and graphical information
Think of product documentation as a road map telling a story about a product. Lead the customer down a path easily identified with screenshots or other graphics and how each different graphic interacts with the other. Explain clearly what the user is looking at or when a feature is activated, how it reacts to the product, and what to expect next. Make sure each graphic is purposeful and that the product's workflow works with each other.
5. Use cross-links for a more precise understanding of topics.
I have found cross-links to be invaluable when reading product documentation. Understanding what a feature or function process does, helps immensely to cross-link to an associated topic. In addition, by cross-linking associated data points, the overall picture becomes more apparent regarding how the system interacts and workflow.
6. Remember the KISS principle for product documentation.
Remember to use the KISS (Keep It Simple, Stupid) principle when creating documentation. However, it is important to thoroughly document the process but not to the point of documentation overkill. In addition, the documentation user may be looking for certain information on specific items, so adhering to the KISS principle permits much easier navigation and understanding of the documentation.
For example, simple notations may suffice to explain a function, perhaps with a reference (cross-link) to the main subject. Keep the facts clean and not over-stated, so the user can easily search for information relevant to their needs. They may not be interested in reading every aspect of the product.
7. Accommodate different styles of learning
Each person has a different style of learning. Some prefer in-depth descriptions, while others may prefer graphics and visual representations. However, some users learn more through hands-on involvement rather than focused reading.
Ensure to encompass all learning styles when creating effective and informative product documentation. For example, inserting graphics like screenshots, graphs, structured text, or video links helps ensure all learning styles understand the product documentation.
8. Personalize and structure onboarding content
Personalize the product documentation based on the role of the audience. Create different versions of the documentation based on the roles of the intended audience when onboarding the content. For example, an administrator's questions may not be relevant to a power user's questions about the documentation.
Documentation can introduce a layer of personalization by creating slightly different versions of the document targeted more to the role of the intended audience. Modifying the onboarding content based on the role of the audience gives the documentation an element of personalization.
9. Clearly define terms for specific audiences
Depending on the intended audience, it is a good practice to explain the meaning of each term used throughout the documentation. You can use more complex terms with some clarification if the audience is internal. However, when external users access documentation, there is no way to know the expertise of the users.
Clearly defining unique or complex terms establishes much better and more efficient communications for all internal stakeholders and external users.
10. Provide a method to collect user feedback
Documentation feedback provides powerful information as to the document's effectiveness. Provide a link or a simple button with "Like/Dislike" to collect valuable information about the quality of the documentation. By collecting user feedback, the documentation can be refined and improved.
11 Avoid documentation with a flat structure
When creating product documentation, make sure the documentation is not written as a "flat structure." Reading a document full of flat text is laborious, and it can also become tedious. In addition, the reader's interest in the documentation will be heightened if the information is relevant to the discussed topic, and a reader can quickly consume it.
Break up the continuous, flat text by highlighting selected information or integrating videos, images, links, and other methods to provide a better UX. In addition, by delivering document content in "bite-size" chunks, the reader will have a more enjoyable experience and be less reluctant to read the documentation.
12. Create documentation that is SEO friendly
An online product documentation best practice is to make sure it is written in a style that is documentation SEO-friendly. Ensuring the documentation is written to maximize search results across the internet for your documentation. Clients may need to search for their documentation, and when they do not have the explicit link to the hosting site, by entering search terms, the responses are quicker and more concise when SEO friendly.
13. Keep the product documentation up to date
Maintaining product documentation maintenance is crucial, primarily if accessed online. Often, the requirements of a product change and the online documentation must reflect any new changes or updates. Therefore, user documentation needs to be current and refreshed for any recent updates and ensure the customer is notified and aware of changes in the product documentation.
14. Understand that users may not read the product documentation
A 2014 study found that users did not completely read all of the product documentation. The primary reasons for not reading the documentation were:
-
Product documentation was overly complex
-
Documentation did not directly address their questions
-
Users did not use many features of the product due to not reading the documentation
-
Rather than reading documentation, many users preferred "hands-on" learning
15. Manage both dynamic and static content
Product documentation continually evolves with updates, new features, corrected content, updated maintenance alerts, and other items. This update is considered a living, breathing document that is continually evolving to the product's requirements.
Static content provides the user with data that does not change across the product's life. The idea for static content is to give references to users, especially new users, information that remains static over the product's life cycle. Static content is vital to rich documentation but typically takes the back seat to dynamic documentation.
Maintaining the documentation set is easier when content is classified as either dynamic or static. The product lifecycle documentation can be implemented and validated easier when documentation is categorized as dynamic or static. There may be minor changes in the documentation for new feature updates (static) or detailed product updates (dynamic).
16. Best practices for product documentation availability
Although users may not necessarily read much product documentation, when they need it, they want it immediately. The traditional delivery method for documentation was to have a printed manual that traveled with the product. However, in today's digital, online world, documentation is often delivered via the web.
Regardless of how product documentation is being delivered, it is essential to have readily available access points. Therefore, the predominate methods of providing documentation today are:
-
Offline documentation - Many products are packaged with printed manuals or "Quick Start" shortcut sheets. These documents are usually "one-offs" and are not easily distributed. However, many manuals are optionally provided in an encapsulated PDF format, promoting portability or the option to print out on demand.
-
Online documentation- Each time you search on Google for an answer to a problem, you probably are grabbing a snippet of online documentation. The advent of the web has supplanted printing manuals or product documentation materials for end users. Some of the benefits of online documentation are:
-
Teleworking - One thing the pandemic taught us is working from home can be productive as the office, especially when our questions are answered with online documentation.
-
Collaboration - With a readily accessible online documentation portal, team members can share information on the fly and create teamwork, which is often impossible at the office.
-
Mobile friendly - The advent of mobile devices such as iPads and smartphones has slowly supplanted PCs for day-to-day interactions. You can easily access online documentation with a smartphone, and any nagging product issues can be readily researched, even at your favorite cafe during lunch.