- Author a high-quality draft for the Knowledge Base
- Enable customers to use a feature in Optimizely
Consider this scenario: you’re a customer with a question about using a feature in Optimizely. You’ve tried to make it work a couple of times, but can’t figure it out -- so you come to the knowledge base to look for an answer. When you click on an article with a subject line that seems relevant, what do you hope to see?
Writing for the knowledge base starts with deep empathy. Customers typically come to the knowledge base to do research, solve a problem, or learn to do something in Optimizely. They typically have a specific question in mind: “How do I …”?
They’re curious, interested, and eager to learn. A friendly, helpful voice meets them where they are; a little humor can make the process delightful.
Customers who read a KB article should think, “Great, I can do this. I’m going to get started!” They shouldn’t hesitate with the idea: “Yikes, this looks complicated. I’ll figure it out later.”
The KB aims to be:
- helpful but not long-winded
- informal but not sloppy
- confident but not overbearing
- precise but not stilted
- lighthearted but not silly
This article walks you through the basics of drafting a KB article on a feature or in-product workflow. Use it as a model for your own draft. It’s meant to provide a framework and lay out core principles; bend or break rules in the interest of the customer you’re writing for.
Have a question? Join the discussion in Slack (#mindtouch) or contact the Education team (@education) by email.
1. Evaluate the topic
One of the first questions that authors ask is: “Where do I start? How do I know if I should write this article?”
Here a few guidelines to help you evaluate whether you should create a KB article:
- The feature is in public beta. Document features once functionality and UI are relatively stable.
- The workflow should be relevant to a core body of customers. Publish with the 80/20 rule in mind; document the 20% of solutions that apply to 80% of people.
- If a solution is too edge case, consider documenting it in the Community or as internal documentation.
- Examples should be public-facing. Examples and use cases help explain abstract ideas; they’re also our most consistent customer request. But before you share, make sure to check that you have permission to use an example publicly.
- Code-heavy instructions that help a developer build a scalable framework should be in the developer docs, not the KB. Once you post a solution in dev docs, link to it from the relevant article(s) in the KB.
- Check for existing documentation. Is there a closely related article in the knowledge base? Update that article instead of creating a new one. Add information where a customer would expect to find it. If your new workflow solves a sufficiently different problem from what you find in any article, consider creating an FAQ or a new article.
Once you validate your article topic, get ready to write.
2. Prepare to write
Think of writing an article as similar to writing an email to a customer.
Who will read this article? Imagine the customer the customer at the other end. Is the customer an analyst, a strategist, a developer, or an implementer? What kind of information do they expect to see and how do they expect it to be delivered?
Start by completing the following statement:
This customer is probably thinking about _______________ when they start reading this article.
What does this article do? Now, imagine what you want customers to be able to accomplish once they read the article. You’ll walk them through the workflow, providing detail and screenshots along the way.
I want this customer to be able to ______________ once they finish the article.
Once you’re in the customer mindset and you’ve identified what you want them to be able to accomplish, try one of the following approaches:
- Find a starting point. Where should your explanation begin? At the Home page? In a specific feature?
- Identify the major sections of the article. Are there natural breakpoints? Different categories to address, or steps to outline?
- Grab the section you know best and start working from there.
The actual process differs for each writer; pick one that you think will work for you. Once you have something down on paper, work your way toward an outline of all the steps. Then, start to fill in the gaps.
Be clear. As the Economist Style Guide notes, “Clarity of writing usually follows clarity of thought. So think what you want to say, then say it as simply as possible.”
3. Build a draft
When you start to fill in the gaps, you’ll break down the workflow into steps. Read on for guidelines for formatting your draft.
Headings and subheadings
A KB article has two levels of hierarchy. Use headings (such as “Build a draft” above) for each major step and subheadings for a second level of options.
The table of contents will automatically populate based on your headings and subheadings. Your headings should be steps, so a customer can scan the table of contents and see what they’ll do.
Ordered and unordered lists
If steps are part of a workflow, use an ordered list. If no specific order is implied, use an unordered list.
Provide screenshots to help the customer find their way. If the process involves a UI component or can be visually explained, use an image.
Add red callout boxes to draw attention to the element you’re working with. Use Mac Preview app to add , and leave a small amount of white-space around the element. When you screenshot a modal, include the contents but not the modal frame itself.
Or, use a red arrow. Open the image in Preview. Click Tools and select Annotate. Then, select Arrow. Point it at the element of interest and resize as needed.
Avoid mentioning the color or style of a particular UI element. For example, say "the Apply Change button" not "the green Apply Change button in the lower left."
Avoid showing the top navigation bar with your username in it.
Use callout boxes to add content to draw customers’ attention to notes, tips, examples, and warnings that aren’t part of the workflow.
- "This article will help you" callouts tells the customer what the article will enable them to do. Bold key phrases to make it easy to scan. Avoid verbs like “understand” or “learn” -- each article should help the customer do something.
- Notes are typically neutral content that provide additional context.
- Tips are snippets of content that benefit the reader.
- Examples demonstrate a detailed concept or solution. Use them to help the customer learn something abstract or complicated.
- Important callouts provide a word of caution or clarify something very important. Use these sparingly.
4. Revise your draft
Once you’ve built your rough draft, revise it for accuracy, readability, and findability.
Revise for completeness
Imagine that you’re a customer new to Optimizely. Are you able to follow your workflow, step-by-step? Is there enough information, or not enough? A KB article should provide focused content and precise instruction, but it shouldn’t be exhaustive -- or overwhelm the customer.
Revise for readability
Readability describes the ease with which a reader can understand what you’ve written. The more readable an article is, the more likely it is that the customer will keep reading.
Start with the problem. Start with the key question or problem that your article solves. This can help you gain the customer’s attention. And, it’s empathetic.
Be concise. Set the stage for readers, but don’t use more words than you need. Keep your paragraphs short -- we recommend 2-3 sentences each.
Be concrete. Abstraction is the luxury of the expert. Be specific. Use examples, if you like. Don’t write in marketing-speak; say what you mean.
Use bite-sized chunks. Dense paragraphs are difficult to parse. Prioritize what’s most important. Consider logical progression of content. Break text into comfortable chunks and use bulleted lists to present information in a clear, skimmable format.
Write actionable headings. Most readers scan until they find the information they’re looking for. Headings, introductory paragraphs, bullets above the fold, and sub-headlines get read the most, so make them clear and actionable. Don’t choose subheadlines that ask, “Why add a snippet?” Instead, state the answer: “Add a snippet to create your first Optimizely experiment.” Bolded key phrases also help your reader scan.
When you’re done, read it out loud. Trim down extra words and long sentences. Aim for a natural rhythm.
More writing tips at a glance
- Simple words; short paragraphs (2-3 sentences each).
- Use the direct form of the verb, most of the time: swim is better than swimming.
- Ditch adverbs. More often than not, they aren’t necessarily as important as you think.
- Use the Oxford comma. This list includes three items, two commas, and a period at the end.
- Use contractions! You’ll sound human, and not like a textbook.
- Use one space after a period, not two.
- Don’t say to users. Refer to Optimizely customers or website visitors.
- Set up is a verb: set up the experiment. Setup is a noun: once you complete setup ...
- Avoid how to. Most of the KB is about how to do something.
- Use Grammarly or another tool to check spelling and grammar.
5. Submit your draft
When you create your draft, create a JIRA ticket to Education to review and publish the article.
Looking for quick resources on writing? Check these out:
If you have more time, try one of these: