Best practices for creating tutorials and FAQs
June 18, 2014 5:43 AM Subscribe
I work for a small web hosting company and have been tasked with creating user tutorials and a general FAQ section. Please give me your best resources, tips, and ideas on how to best go about doing this.
I have already begun creating style sheets for them all, so as to present a unified aesthetic (e.g., serif fonts for titles and formal names, sans-serif for body text).
I have also been creating screenshots of our user control panel.
As far as general writing style goes, I am trying to be as straightforward and to the point as possible, keeping jargon to a minimum, avoiding digressions by creating/linking to substantial items deserving of their own pages, etc.
If you have created such, please tell me what you did that worked best, what didn't.
If you have ever used a web host's online FAQ or support, tell me what you liked, what you didn't.
Thanks!
I have already begun creating style sheets for them all, so as to present a unified aesthetic (e.g., serif fonts for titles and formal names, sans-serif for body text).
I have also been creating screenshots of our user control panel.
As far as general writing style goes, I am trying to be as straightforward and to the point as possible, keeping jargon to a minimum, avoiding digressions by creating/linking to substantial items deserving of their own pages, etc.
If you have created such, please tell me what you did that worked best, what didn't.
If you have ever used a web host's online FAQ or support, tell me what you liked, what you didn't.
Thanks!
Best answer: You sound like you're on the right track! Being straightforward and avoiding jargon are both really important things to keep in mind. Further to that, you want to always ensure you are using language that is as clear, precise, and familiar as possible. So that means using plain and simple language (e.g. instead of "facilitate", use "help". Instead of "utlilize", go with "use", etc.), and avoiding vagueness and ambiguity.
Watch out for screenshots as they can become outdated very quickly as soon as anything in your user interface gets updated. It's a lot easier to update text than it is to update a screenshot. Screenshots can be really helpful but if your copy is good you don't necessarily need them.
Alongside the style sheets you might want to put together a quick editorial style guide which gives you some guidelines for how to approach things such as:
* Headings - title case or sentence case?
* What words get capitalized?
* Bold or italics for emphasis?
* Full stop after bullet points?
* Do I refer to this feature as the widgeywoo or the doobywhack? etc. etc.
As you build out a library of documentation you will need to make lots of little decisions along the line about this stuff and it helps to have them all written down somewhere so that you can ensure you are being consistent. You can Google around for some good examples of editorial style guides but most of the ones online will be more complex than it sounds like you need.
And perhaps the most important thing to always keep in mind when writing user documentation: put yourself in the shoes of the person reading it. Imagine you don't know the first thing about web hosting. Would these instructions make sense to you? Could you follow these steps and get the outcome you wanted? Could you understand the meaning of this sentence without reading it multiple times? Make sure you are stepping through the processes yourself while writing the tutorials to ensure you don't miss anything.
posted by RubyScarlet at 6:16 AM on June 18, 2014 [1 favorite]
Watch out for screenshots as they can become outdated very quickly as soon as anything in your user interface gets updated. It's a lot easier to update text than it is to update a screenshot. Screenshots can be really helpful but if your copy is good you don't necessarily need them.
Alongside the style sheets you might want to put together a quick editorial style guide which gives you some guidelines for how to approach things such as:
* Headings - title case or sentence case?
* What words get capitalized?
* Bold or italics for emphasis?
* Full stop after bullet points?
* Do I refer to this feature as the widgeywoo or the doobywhack? etc. etc.
As you build out a library of documentation you will need to make lots of little decisions along the line about this stuff and it helps to have them all written down somewhere so that you can ensure you are being consistent. You can Google around for some good examples of editorial style guides but most of the ones online will be more complex than it sounds like you need.
And perhaps the most important thing to always keep in mind when writing user documentation: put yourself in the shoes of the person reading it. Imagine you don't know the first thing about web hosting. Would these instructions make sense to you? Could you follow these steps and get the outcome you wanted? Could you understand the meaning of this sentence without reading it multiple times? Make sure you are stepping through the processes yourself while writing the tutorials to ensure you don't miss anything.
posted by RubyScarlet at 6:16 AM on June 18, 2014 [1 favorite]
Wiki-style software is good for FAQs.
PBWorks is one with which I am familiar, but there is lots of this kind of software out there.
posted by dfriedman at 6:17 AM on June 18, 2014
PBWorks is one with which I am familiar, but there is lots of this kind of software out there.
posted by dfriedman at 6:17 AM on June 18, 2014
Mobile device friendly version if you expect or see a significant number of mobile browser user agents on your site statistics pages.
posted by Buttons Bellbottom at 6:41 AM on June 18, 2014
posted by Buttons Bellbottom at 6:41 AM on June 18, 2014
Best answer: When I work with my colleagues to write tutorials, we start by defining the user's starting state and what we want her end state to be. For example, the starting state might be that the user has a browser window open to google.com, and the end state is that she has submitted a comment on an AskMe post. From there, you can fill in an outline of the concrete steps that she must take to get to the end state. Then, you can flesh out each step with explicit instructions about where to click, what to type, etc.
It sounds simple, but we've found that if you start writing without a clear outline, it's easy to veer off into long explanations of background information, which isn't what you want in a tutorial.
As RubyScarlet pointed out, be careful with screenshots. Be sure you add them only where they add value, not just for the sake of having them. Sometimes it's better to crop a screenshot and only show specific button or field, rather than the whole screen. SnagIt is a great tool for this.
Personally, I don't like FAQs that only contain answers to very specific, obscure questions. I find it useful when an FAQ starts with a few general questions about the company/products, and information about how to contact customer support.
Keep in mind that you should use terms that your users are likely to search for. For example, if I search for "shut down the server" but your documentation says "stop the server", I might not find the information that I need. Metadata can help with this.
If you're struggling with any writing style issues, you can try consulting the Microsoft Manual of Style for Technical Publications. It's pretty commonly used in the technical writing world. Microsoft used to provide a PDF version of the third edition for free, so you may still be able to find that online. Or you can pick up the fourth edition for $22.
Oh, and remember to keep a version history of everything you write. Consider using a content management system, if you aren't already.
posted by neushoorn at 7:09 AM on June 18, 2014 [2 favorites]
It sounds simple, but we've found that if you start writing without a clear outline, it's easy to veer off into long explanations of background information, which isn't what you want in a tutorial.
As RubyScarlet pointed out, be careful with screenshots. Be sure you add them only where they add value, not just for the sake of having them. Sometimes it's better to crop a screenshot and only show specific button or field, rather than the whole screen. SnagIt is a great tool for this.
Personally, I don't like FAQs that only contain answers to very specific, obscure questions. I find it useful when an FAQ starts with a few general questions about the company/products, and information about how to contact customer support.
Keep in mind that you should use terms that your users are likely to search for. For example, if I search for "shut down the server" but your documentation says "stop the server", I might not find the information that I need. Metadata can help with this.
If you're struggling with any writing style issues, you can try consulting the Microsoft Manual of Style for Technical Publications. It's pretty commonly used in the technical writing world. Microsoft used to provide a PDF version of the third edition for free, so you may still be able to find that online. Or you can pick up the fourth edition for $22.
Oh, and remember to keep a version history of everything you write. Consider using a content management system, if you aren't already.
posted by neushoorn at 7:09 AM on June 18, 2014 [2 favorites]
I also found the Microsoft Manual of Style to be very useful for writing tutorials. (I downloaded the third version for free somewhere.) It's very opinionated and just says "this is the correct way to do things," so you might not follow all of it, but it is well reasoned and consistent.
posted by smackfu at 7:21 AM on June 18, 2014
posted by smackfu at 7:21 AM on June 18, 2014
Please make sure you have a person that was not involved in the development of the tutorial test the procedure. Ensure that the procedure is tested on a fresh operating system that has never been configured to use your system before. This will help test your assumptions.
It would be even better to get a member of the target audience to test the procedure. If the tutorial is intended for the general public, see if your company will spring for a gift card to get someone's spouse, sibling, parent, or friend from outside the company to test it. This feedback is important.
posted by crazycanuck at 8:37 AM on June 18, 2014
It would be even better to get a member of the target audience to test the procedure. If the tutorial is intended for the general public, see if your company will spring for a gift card to get someone's spouse, sibling, parent, or friend from outside the company to test it. This feedback is important.
posted by crazycanuck at 8:37 AM on June 18, 2014
If there is a ticketing system, try to go back through the last two years (or however long) and determine a threshold: if a question was asked X times, it gets an entry in the docs. X could be 2 or 20.
Seeing the tickets or chat logs can help with language as well, as you'll see all the terms that people are using when they try to describe the problem and can include them in the article, as keywords, or tags.
posted by jsturgill at 10:16 AM on June 18, 2014
Seeing the tickets or chat logs can help with language as well, as you'll see all the terms that people are using when they try to describe the problem and can include them in the article, as keywords, or tags.
posted by jsturgill at 10:16 AM on June 18, 2014
Best answer: Here are some sites to look at and get a feel for how others do it:
linode
webfaction
digital ocean
a small orange
media temple
dreamhost
pair
hostgator
Also, try to use symantic elements to focus search engine attention. I routinely use Google to search for knowledge base articles instead of the actual knowledge base's search engine. Many/most visits to your support site may well be clicks from a google searche for "[company name] [problem]" rather than from users navigating the support system.
posted by jsturgill at 10:36 AM on June 18, 2014 [1 favorite]
linode
webfaction
digital ocean
a small orange
media temple
dreamhost
pair
hostgator
Also, try to use symantic elements to focus search engine attention. I routinely use Google to search for knowledge base articles instead of the actual knowledge base's search engine. Many/most visits to your support site may well be clicks from a google searche for "[company name] [problem]" rather than from users navigating the support system.
posted by jsturgill at 10:36 AM on June 18, 2014 [1 favorite]
Best answer: MailChimp has a great kb, and their videos are super helpful as well.
posted by radioamy at 11:17 AM on June 18, 2014
posted by radioamy at 11:17 AM on June 18, 2014
Response by poster: Thank you for the all the excellent answers, good peoples. This all helps a lot.
posted by jammy at 4:29 AM on June 23, 2014
posted by jammy at 4:29 AM on June 23, 2014
« Older How do stop Gmail/Mail from sending emails to a... | Adding depth to "old-school" RPGing Newer »
This thread is closed to new comments.
posted by mbarryf at 6:03 AM on June 18, 2014 [7 favorites]