Best practices for creating how-to articles for Knowledge Base

Hey Devon!

This is a really great question! I'll see if I can find some Moderators to share any wisdom they have, and hopefully others in the Community will weigh in as well.

In the meantime, if you haven't seen it already, we have some great best practices documentation that you might find helpful! You can find a list of everything here:

• Self-service best practices docs and tips

Hi Devon,

I'm not exactly in the same industry as you, but I'm partial to the Q & A format. Focusing ruthlessly on one or very few issues within any single article.

You mention templates, so I would like to recommend (if you haven't already) that you check out the Knowledge Capture App (currently in early access) that lets you create templates in the Help Center for fast and consistent re-use of any particular format. We use multi-lingual content, so it's a real time saver having a single template that has all Headings and other formatting pre-selected for each language.

Great question Devon and this what we do for a business, write the content!

Every company is different but the standard would be something like this.

1. Title. This directly refers to a customer objective or task. Don't let your engineers give you spec titles
2. Description. Should include what, why, perspective and example. Don't just say "This feature allows you to create a new user". You should say what creating a user would do for you and an example of when to use it. My example is not a good one but you get the idea. Remember, a customer (or pre-sale prospect) will read the first paragraph and then decide to read on or not. Some write with a marketing feel as well. 
3. Dependencies and related links. If that's necessary. But give user all info needed before the actual procedure.
4. Write your process. Use screenshots when they add value or you think your users will read the content without the app in front of them. Try to add points that aren't obvious from the screen. Info that adds value.

Add a Workflow or Best Practices chapter. These you know best and often involve a number of tasks. Provide the basics and then links to the other relevant articles to complete the process.

I hope this helps a little. More questions, feel free. 

Thanks, Steve and Jacob! Great answers.

I would add, that if you are writing a how-to, you should use numbered steps for your procedure. And include only one action in each step. Start with an action verb--"Click this" or "Enter that."

You can get some more tips in this section of our "Develop content for your knowledge base" article. In that section there is also a link to the community discussion we did to create that article.

Let us know how it goes! And good luck with your KB.

Thank you all - this is all very helpful!

Would any of you be interested if I ran a free 1 hr webinar to give you the basics of how to write good content? No work for me as the content is ready. If interested, please comment. 

Hello Devon,

Just a few thoughts (which you may have already !thunk!

Smaller & Modular: We're in SAAS too, and we're more partial to smaller & modular articles that are housed together in Zendesk Sections to provide a sequenced flow. We also cross link among articles for follow-on or dependent processes' articles.The advantages to this are a lighter lift when the UI changes (which can be frequent), because you have just one (or two) places to made edits. And if you want a more comprehensive guide, you can always piece it together by linking to the smaller articles, with explanatory text as the glue. 

Personally, I dislike searching and scrolling through a loooooong article to learn how to perform one small task, like create a password.

For linear, multi-step flows, we use buttons (links) at the bottom to move to the next and previous steps.

Audiences: We also have two specific roles that we create different portals for: platform administrators and end users. There is not a lot of overlap in their processes, so they have separate articles, accessed via different portals (Zendesk Categories). 

Thanks for all the great comments, everyone! Keep them coming!