When writing documentation, keep in mind the types of people who will use it. Sometimes these vary a bit, and we may need to create separate content for different users.
Avoid using marketing language. It is important to remember that documentation is not sales content. Even prospective users may be looking at these materials to see how they will be treated once they are customers.
Use different language styles for different user-types. Users of the product can be divided into a few categories:
While we cannot address all types of users with a single document we strive to provide varying forms of content.
These can include:
Avoid using jargon for basic tutorials and how-to guides, however it is permissible to use it for more advanced users. For example, it’s permissible to use industry jargon for developers.
Content is typically organized into short articles or guides, and grouped into larger categories. Arrange articles in a logical hierarchy, so users can read through each article as part of a larger tutorial. Consider using relevant keywords or synonyms within an article to ensure that it can be found when users are searching for specific content.
Users often find articles through searches, so don’t presume they are already familiar with related content. Treat each article as if it’s the user’s first encounter with your material. If you can’t include introductory information in every article, consider adding links to other supplementary content to help users get oriented.
There are cases where shorter articles don’t necessarily meet the need of a specific type of guide, such as, for example, printable PDF files. In this case, organize content using clear headings.
Organize content within individual guides and documentation by using clear hierarchical headings. Good headings make it easier for readers to identify which sections of a document are most relevant to their specific issue. They also help search tools find relevant content if someone uses this method of finding solutions to their problems.
Instructional articles follow a relatively uniform structure.
They take the following format:
Organize instructional articles into tasks. Typically users will go to documentation to find out how to perform a specific task. Try to think of all of the tasks that a user may wish to complete as part of their daily use of the Heartland product. Arrange content to answer these types of questions. Consider structuring articles around user actions, rather than product features.
Note: It can be helpful to create a structured map of the application for those users looking for a quick reference to features.
Tones may vary depending on the action that a user is attempting to perform. Here is a list of acceptable tones that can be used, and where they may be appropriate.