Summary: Write product documentation that is easy to scan, keyword rich, and provides immediate answers to customer queries. To help users find information quickly use short headings, front load keywords, and categorize related content into sub-headings.

How To Create Product Documentation

Use the following checklist to document all aspects of a web application.

Conceptual Information

Describe the main features in the application.

Imagine if someone had never visited your web application before.

What would they need to know about the most important features to make sense of how the system works?

To do this, provide some background, describe a typical business scenario or use case, and some examples that put this in context for the reader. Context is important here as it helps the reader understand how the web application will address their specific needs.

Procedures

So, what can a person do with your system?

Break out the different tasks they can perform with your software application. Prioritize the most important ones and document these first.

How can you ensure that your procedures are accurate?

To test them, print out the procedures and ask another person, for example, someone not in the IT department or has worked on this project to follow the instructions.

Reference

This refers to technical documentation, typically aimed at software developers. For example, if your product offers a set of APIs, then you will need to document the endpoints, parameters, and provide code samples to help the developers get up to speed with the APIs.

You might also consider having a section that describes the purpose, function, and settings for any item which can be configured in the system. For example, if your software allows the user to configure different calendars, currencies, or notification settings, explain where and how to do this — and how their experience on the site will be affected.

Internal and External Linking

Just because a link works doesn’t mean that its correct. Check that buttons, images and text link to the correct page?

Check for broken links if you are using a Help system to provide context-sensitive help.

Static Pages

Check the accuracy of static pages, such as Privacy, Copyright and FAQs. Make sure the content is accurate, in the correct language, and has not been update by others ‘on the fly’ which often introduces other errors.

Screenshots

Make sure there is no customer data in any screenshot. Likewise, remove ‘dummy’ data entered by testers. Create meaningful test data for the screenshots.

Metadata

Check that the metadata for each page is correct. Ensure that there are no duplicate metadata tags or confusing page titles. One suggestion is to define a naming structure for the pages, so there is common naming across the application. This ensures that other team writers follow the same conventions and minimizes the need to update or correct pages later in the publishing cycle.

Branding

Check that the logos, icons, and other branding-related imagery is correct. Also, review straplines and other marketing messages to ensure that it’s accurate, consistent, and current.

Buttons

Is the text on the buttons correct? Could a user misunderstand any of the buttons? Check that the mouse over text is accurate, grammatically correct, and provides useful information to the user. Refine mouseover text where necessary.

Popup text

Many web applications include popup text that provides additional information to users. In many cases, this is added in manually by developers, sometimes on an ad-hoc manner. For this reason, check every page which offers popup text and study the text carefully. If possible, try to get access to the resource file where this text is stored.

Error Messages

Create generic warning, information, and error messages before the project starts. Use these in scenarios where you simply want to flag a common issue and the steps the user must take to resolve it.

In other scenarios, you need to provide very specific instructions, especially if there is a risk that the user might lose data.

Examples of how to write an error message.

Mobile Content

Writing technical content for mobile devices presents challenges for technical writers. If users will be accessing your web application over a mobile device, write the content so that it can read on a small screen and doesn’t require excessive scrolling to understand the text.

Language

Decide which language to use for the web application, typically US English. Check for spelling on words such as licence v license. Modify colloquial phrases into more formal language, making it easier for translators.

Where did they get confused? What steps were unclear? Were they able to perform the task without assistance?

What suggestions did they have to improve the quality of the documentation?

How to Plan your Documentation

Use the following approach to document your web application:

1. Identify each procedure that requires documentation.
2. Go through each procedure to understand how it works.
3. Makes notes, get clarifications, and ensure your understanding is correct before you start.
4. Document the procedures, references materials, online help, and error messages.
5. Print out and test the documentation against the website. Makes notes of changes which may have occurred since you starting drafting the materials. Technical writers working in an Agile environment need to be more aware of this.
6. Send the text for review. Remind reviewers of deadlines and their responsibility to confirm the accuracy of the content.
7. Update the web content based on their feedback.

Make a note to do spot checks and periodically review and update the content.

How to Write Product Documentation

Here are some dos and don’t when writing web content, for example, for SaaS applications.

Do

• Identify a single writing tasks – a procedure, error message, or concept.
• Highlight the steps that need to be performed before this starting this procedure
• Use the default settings. Explain how to use additional optional settings
• Identity mandatory steps, fields, or conditions that must be applied.
• Describe steps in the correct sequence.
• Describe optional steps and the consequences of each action.
• Version control working drafts.
• Archive redundant drafts to avoid contaminating the documentation set.
• Update the table of contents before you publish the content

Don’t

• Take screenshots early in the process as these are likely to change.  
• Assume the reader knows where this screen is located in the application.
• Merge multiple procedures. Identify and document each procedure.
• Confuse number and list items.

What to include in Product Documentation?

So, what should you include in your online documentation?

If you plan to include a Help section on the site, the following topics are worth considering as these apply to most all web applications.

#1 Getting Started Guide

Explain to the user how to get started, setup, and perform common tasks on your site/application.

For example:

• Share a folder
• How do I get notified of changes?
• My options to share files look different—did something change?

#2 Top 5 questions for specific areas

If you look at Google Analytics, you’ll see the type of questions customers have and the most common issues that keep arising. With this in mind, identify the top 5 issues they have for billing, security, or whatever area that needs attention. Update this periodically.

• There’s a charge on my credit card—which account is this for?
• Canceling—refunds and other information
• Invoices and receipts for subscriptions

#3 Frequently asked questions

Similar to above, answer the most frequent questions that your technical support team has to deal with. This will probably include standard responses that will reduce the work load on your support team and alleviate whatever concerns potential customers may have.

FAQs are often for prospective customers, where the Top 5 type questions are for customers currently using the website application.

Examples may include:

• Is this site safe to use?
• Sharing an account with someone else
• Does it work on Apple Mac?

#4 Policy and compliance

You must have a section about data protection and how you protect the user’s account.

Typical Help topics include:

• The copyright policy
• Where do you store my data?
• How do I delete my data?

#5 Account settings

The first thing most users do when they create a new account is to personalize it.

Explain how to setup their profile, add an avatar, configure notifications, setup security settings, and how to link their account to social media platforms.

Help topics for account settings may include:

• Set a profile picture
• Supported languages for apps
• Opt out of emails

#6 Help

Use the Help section to gather questions related to technical configuration, system requirements, accessibility, and other issues related to getting started.

• How to use
• System requirements and browsers
• Accessibility

Summary

Provide documentation that encourages customers to use your products and recommend it to their colleagues. Use best practice web writing guidelines to craft pages that help users find information faster, direct them to the correct sales page with the least effort.