Reader Question: How do I create online help, how to guides, quick start tutorials, or video tutorials?

by Tom Johnson on Sep 11, 2013
categories: technical-writing

A reader asks,

I find your advice extremely helpful, thanks! Where can I get instruction to learn how to do 10-A tech writing deliverables, Is there a guide or open course university to show you how to write online help, how to guides, quick start tutorials or video tutorials? Thanks,

It's not often that someone asks for advice for such all-encompassing instruction in tech comm, so I thought I'd take a stab at actually answering it. Exactly how do you create online help, how-to guides, quick start tutorials, or video tutorials? Here's a 10 step process to follow:

1. Analyze the needs of your users. It all starts here. Never simply document the features of the application. Instead begin by asking what users want to do, their core tasks and responsibilities, and how the application might assist them with these goals.

2. Make a list of the articles your users will need. These articles will include the instruction that you write. Don't worry about being exhaustive. Just make a list to get started. As you begin creating the content, you'll have many ideas for more information that's needed.

3. Get access to your product and explore it. You'll need access to development environments, test logins, bug tracking tools, and other related sites and assets to explore the product (usually a web application in IT). Ask your product manager or lead developer for this access. Explore the application in terms of the list of articles you want to write. You may need to set up demos with developers.

4. Start developing your help material. I like to write content in Google Docs because it's so easy for my developer colleagues to review. The commenting features for Google Docs are unparalleled and allow lots of back and forth exchanges. But you could start writing anywhere. The key is not to get mired into structure and format at this stage. Just focus on the content.

5. Review your content with subject matter experts. Ask your product manager which person will be the designated reviewer, and make sure to follow up with the person about his or her preferred method for review. If the person doesn't get around to reviewing anything, consider setting up a meeting to review the content during the meeting.

6. Figure out what formats you need to publish the content in. If no one has asked for a lengthy PDF document, don't assume you need to provide one, especially if your product is web-based and you're in an agile environment. With agile, things change quickly so any PDF you create will be out of date. Eliminating the print deliverable can simplify publishing considerably. If people really need something printed, consider creating a printable quick reference guide (2-5 pages).

7. Select a publishing destination. My preference is for a web-based platform like Mediawiki, Drupal, or something else. But really, there are many tools out there, from Flare to Robohelp to ClickHelp, Doc-to-Help, and more. What's right for one situation may not be right for another, but my advice is not to get overly caught up in tools. Keep your focus on the content.

8. Convert your help material from your scratch pad area (e.g., Google Docs) to your tools and publish the material. The conversion from the scratch pad writing tools to the formally published output will invariably introduce errors and other formatting issues that you'll need to fix and address. Get the help material looking sharp.

9. Create quick reference guides that pull out significant, overview-like material into a highly compressed guide. You could create a quick reference guide using something like Microsoft Word, Adobe InDesign, or single-sourced perhaps from your help authoring tool. The main point with a quick reference guide is to be brief, basic, and visual.

10. If you need video tutorials, pull from your help material to create several 300-word scripts. You don't need a ton of videos. They're mostly introductory for new users, so cover the basics. I prefer Camtasia Studio as my video tool and publishing on Youtube or Vimeo. Make sure you embed the videos into the appropriate places in your help material.

At a high level, that's about how I go about creating help material. I realize that you're probably a student (from the "10-A writing deliverables" reference in your question, whatever that means), and if so, a classroom environment is different from a real environment. But this is the general pattern. I invite readers to share their answers for creating help material.