Every technical writer has their own process for publishing outstanding content. But there are some timeless principles that might help you. In this article, we will show 14 super handy publishing checklist for SaaS user documentation that every technical writer can follow to publish awesome content.
This guide goes hand-in-hand with our more specific post on how to write a great knowledge base article.
So how can you get started?
1. Start with an introductory overview
Writing knowledge base articles is not like copy-writing or blogging. You need to get straight to the point – fast.
If your documentation is solving a problem and is task-based, you should include the solution in the introductory paragraph. Give away the good stuff straight away. Users who don’t need step by step instructions can learn what they need to and move on.
Similarly, if you are offering video content as your documentation, then you’re forcing users to devote time to watch a video. This sometimes unnecessarily restricts users who want to skim read the answer. Always combine text and video together.
2. Use numbered or bullet point lists
Lists are great for documentation because they improve users’ ability to scan. In a task-based article, numbered lists of steps are the best way to get your point across.
Review your article and ask yourself: is there any information that could be split up into a numbered list, rather than a chunky paragraph?
Things that could be split up into lists:
- Steps
- Alternative options
- Configurations
Here’s an example of an article that includes a numbered list from Buffer:
3. Include subheadings
Another great way to break up your text from being too long is to include subheadings. Subheadings help users scan your content more quickly and improve readability.
Subheadings should be around five words long and descriptive about the section. Each section should be no more than around three paragraphs, and each paragraph should contain no more than about three sentences.
Limit yourself to one subtopic per subheading.
Twitter actually uses a great table format to separate out subtopics within a single knowledge base article:
And they’ve also included a list for extra readability!
4. Check for plain writing
Tools like Hemingway can help you make your writing as clear and easy to read as possible. You may even find out after using them regularly that plain writing becomes second nature.
Plain writing is not about making your writing boring. Plain writing is about clarity – which is exciting in its own way.
Consider the difference between these two sentences:
- Make sure that you remember everything important when you leave, like your keys, phone and wallet.
- Remember to take your keys, phone and wallet with you when you leave.
Read through your article and ask yourself: What are the possible interpretations here? If you can imagine more than one interpretation, refine your presentation and word choice until there is only one possible interpretation – the correct one.
How many separate bits of information must readers hold in their minds at once for your meaning to become coherent? Get right to the point in every sentence to remove the possibility of readers forgetting previous information, and becoming confused or disoriented.
Simple and intuitive knowledge base software for your business needs
Learn more
Make your writing more plain by:
- Choosing the most accurate, simple terms
- Breaking your sentences down into only one or two clauses
- Using correct punctuation like commas and dashes
- Writing in a semi-formal conversation style
- Deleting any unnecessary words.
Pro tip: A great shortcut to plain writing is to pick some writing by another author that you admire for its plainness, and then imitating the style. Try to tease out the elements that you think make the writing clearer, and use them in your own writing.
5. Get rid of passive voice
This one relates to plain writing but deserves a section all its own. Passive voice is when you place the emphasis on the object rather than the subject.
Most sentences in English have a subject and a verb. The subject is who or what your sentence is about, and the verb describes an action or state of being.
Writing in the active voice means the subject is doing the action. The opposite is passive voice, when the subject is having the action done to them.
Most technical writers prefer to use active voice in documentation because it’s clearer and more direct. This is best illustrated with an example:
ACTIVE VOICE: ‘the user [subject] clicks the button [object]’
PASSIVE VOICE: ‘the button [object] is clicked by the user [subject].’
The latter is much more wordy, and slower to read, than the former. Eliminate passive voice from your documentation as far as possible.
Pro tip: The free tool Hemingway will tell you when you’re using passive voice by highlighting the text.
6. Include images
Sometimes your documentation is improved with a simple screenshot or diagram – especially when you’re describing a lot of tasks based on a software interface. An image is worth a thousand words, after all.
Make sure your images are not the only way you are conveying meaning. This is because images are not accessible, may not load, and may not be viewable on a small screen (mobile device) anyway.
For example, Chargify – an online billing software – includes a custom illustration for their Getting Started documentation:
Custom illustrations may not be within reach of everyone, but perhaps generating a diagram or screenshot might be possible.
If you include images, make sure each one has an ‘alt text’ tag filled in with a description of the image so screen readers can read it. This is an integral component of optimizing your knowledge base for SEO. We will cover this in-depth in a subsequent section.
7. Edit and proofread
After you draft your work, subject it to a rigorous editing process.
Unfortunately, professional editors are hard to come by these days, and it’s hard to proofread your own work. Grammarly is a free tool to help you do just that. It won’t catch everything but it’s a good place to start.
They say that good writing is mostly good editing – and it’s true.
Pro tip: Ideally you should draft your article, leave it for a day, and come back to view it with fresh eyes. If you’re short of time to edit your article, you can change the font and colour of your document and read through it backwards.
We tend to skim-read our own writing and assume we know what’s there, making us miss errors. This will trick your brain into viewing it more objectively.
8. Conduct peer review
Nothing beats peer review for documentation. If you’re lucky enough to be a team of technical writers, build this into your documentation process.
Ideally, if you’re documenting a special topic and teaming up with a Subject Matter Expert, get that same person to take another look over your work to check you’ve got it right.
Part of the peer review could be testing that your solution actually works! If you have time, check for multiple environments like different browsers, versions of Windows or different Operating Systems.
9. Check the style guide
When you have more than one person writing knowledge base articles, it’s easy to end up with a bunch of different formats and styles. It’s confusing for users if you don’t have a coherent presentation and brand.
Unlock the power of writing. Developed with love for technical writers
Get started nowEven if you’re the lone technical writer, the person writing today is totally different to the person you were several months ago.
That’s why you should have a style guide for your knowledge base. This includes things like:
- Formatting (bold, italics, underlined, colours, fonts, links)
- Person (first, second or third)
- Capitalisations
- Headings
- Numbers
- Dates
- Oxford comma
- Acronyms
- Abbreviations
Check that your article matches the style guide. If you don’t have a style guide, create one now!
10. Assure consistency
Consistency is an important part of good writing in general, as well as successful branding. Your style guide should be the source for all your technical terms, product features, and other terminology.
It matters less how you choose to present your documentation than having consistency with your choices. This relates to your style guide but goes beyond style.
Some people will get annoyed with your stylistic, grammatical, formatting or word choices, but the most important thing is to keep them the same throughout.
For example, don’t say the number ‘4’ in one part of your knowledge base software, and ‘four’ in another. Don’t refer to your company as ‘The SaaS Company’ in one place, and ‘SaaS Company’ in another. You get the idea.
11. Use interlinking
Interlinking in your documentation helps with content discovery, comprehension, and accessibility. Your users can be arriving at your content from any angle (as opposed to the homepage) so they don’t necessarily know where your article fits into the larger whole.
Linking between your content builds a picture of the structure of your knowledge base in your user’s mind. By proxy, that will also be an impression of your product.
Remember this especially if you’re writing an article in a series that you expect to be read chronologically. Link to the previous and subsequent article for ease of navigation.
Link from every term that you use in your company knowledge base that might not be immediately understood by the majority of your users. Depending on your product, not everyone may be familiar with the term ‘deploy’, for example. Link to a good definition if you use specialist terminology.
Pro tip: Conduct a review of your knowledge base structure to find out if you can improve the navigation, and discoverability of your content.
12. Conduct user research
Remember – you are not your audience. You’re so close to the product (and the documentation) that you have knowledge and insight your users are lacking.
If you have the time and resources, testing your documentation in front of actual users is the best measure of its efficacy. You can print out the pages of your content, or just the text, and ask users if they understand what it means. If you can’t get in front of real users, try doing it online.
Make your knowledge base easily searchable on the internet
Get started todayConducting a user research test will be very revealing in terms of your content’s usability. This may not be possible for every single article – or even most articles – but testing every so often will help keep you on track.
Pro tip: Watch out for the Hawthorne Effect – users will try to please the researcher when observed. The results you end up with may not always reflect actual usability.
13. Think about search engines
Optimize your knowledge base article for search if you can. You’ll increase traffic to your content over time from existing customers using search engines, and potential customers browsing the same topics.
This means including things in your article like:
- Filling in the metadata
- Tagging with appropriate keywords
- Optimising for a keyword string (if you have one in mind)
- Using h2 tags for subheadings
- Alt text for images
Ideally, SEO should be designed into your whole documentation strategy. Your knowledge base must be optimized to properly indexed by search engines and content should match real user search queries.
Any knowledge base software you use should have this functionality built in. Document360 has all this and more.
14. Ensure accuracy
In a SaaS company, it’s likely that your documentation is going to become out of date very quickly – and that’s fine.
Perhaps you made assumptions and actually made some mistakes in your documentation. This is one reason why the peer review process is so important.
Or did your engineering team release another version of the product while you were writing the docs, and forget to tell you?
You don’t want to tell your users to click on ‘funny widget’ when it’s actually now called ‘silly widget’. Inaccurate documentation breaks trust with users, and is arguably worse than none at all.
Factor potential inaccuracies into your content production process. Comb through your documentation deliberately looking for errors.
Pro tip: Ideally, your technical writers will work closely with developers using the docs like code methodology. This is where you keep your documentation in the same place as the source code. Technical writers and developers use the same tools, and docs are considered a condition before you can release code.
Final remarks
Use this publishing checklist to write awesome knowledge base articles that will delight your users.
You won’t always have time to do everything on the list, but if you build most of these into your documentation process you’ll be creating a knowledge base to be proud of.
Let us know in the comments section below if you have any more things to add to this checklist!
–