Blog > Versoly

How to write a style guide for your help docs

By Jonny Holden

Published February 10, 2023

Updated April 26, 2024

Audience

The intended audience for the help docs is primarily users of the SaaS product. The language used should be easy to understand and avoid using technical jargon, unless you know that the user will have a good level of understanding. Remember, sometimes it's easier to understand the "jargon" in a field, than to understand a more "simple" way of writing things.

Tone

The tone of the help docs should be friendly and helpful. Use a conversational tone to make the information easy to understand and approachable. Imagine that you are looking over the user's shoulder and giving them helpful advice.


Format

Use headings and subheadings to break up the text and make it easy for users to find the information they need. Use bullet points and numbered lists to organize information. Use screenshots and videos to illustrate how to use the product. Technical Writing One is a useful course from Google.

Voice

Use the second person voice (you, your) to address the user directly.

Grammar

Use proper grammar and punctuation. Avoid using slang or colloquial language. This is especially true when your users may not be native speakers of your language. While it's true that people learn "it's raining cats and dogs", they might not understand "a cat in hell's chance"!

Capitalization

Use sentence case for headings and subheadings. It's much easier to scan and understand. Capitalize UI (user interface) words, such as "Print button" and "Save".

Branding

Use the SaaS product's branding, such as the logo and color scheme, throughout the help docs. Keep the docs on the same domain as the marketing pages for better SEO. If you must use a sub-domain, always link to the webpages and the app from the docs.

Linking

Use hyperlinks to link to relevant information and resources within the help docs and on the SaaS website. This helps people find additional information, and will help convert visitors into users.

Feedback

Encourage users to provide feedback on the help docs and use that feedback to continually improve the documentation over time. Hyvor Talk creates a comments section at the bottom of your docs.

Update

Keep the help docs up-to-date with any new features or changes to the product.

In conclusion, the help docs should be easy to understand, approachable, and helpful. Using a consistent format, simple language, and a friendly tone, users can easily find the information they need to get the most out of the SaaS product. It is important to keep the help docs up-to-date and encourage user feedback to continually improve the documentation over time.