Tech Writing 202: How To Articles and Tutorials

So you've decided to write a Tutorial. Excellent, let's get started.

Below are the requirements and guidelines for Tutorials and How-to articles.

Requirements

• Word Count: 500-1200 words
• Image Usage: Important and recommended. Usually, each step should have an image to guide the reader.

Image Usage

When using images for your how-to and tutorial articles, ensure that they follow these guidelines:

• The most common type of image used will be a Screenshot. Your images must follow the guidelines set by the Screenshots section of Tech Writing 103: Technical Difficulties. In summary, screenshots must clearly display all relevant visuals with boxes and arrows, should not be unnecessarily large in size, and have any sensitive or personal information edited out.
• Any brand images that you use should be under proper licensing. Be aware that not all companies allow free usage of their branding.

Formatting Guide

Contents

1. Introduction to Problem: Your article should start with a brief introduction to the problem the article is solving. A personal story about you running into the problem yourself is a good intro. You can also describe the featured product or process in this section.
2. Solution Showcase: Before going into the tutorial steps, show a demo of the solution or the final product first. Doing this makes it easy for the reader to understand what they will be able to do by the end of the article.
3. Steps to Solution: Next, outline and set the required steps of the solution. Try not to have any tangential steps and keep the instruction as simple as possible. Use as many screenshots as you deem necessary. Your steps should be concise, efficient, and follow a logical path to the final result.
4. Demo and Conclusion: Finally, conclude your article with a short summary and display the solution again as a final product demo.
5. Troubleshooting: It is a great idea to include a Troubleshooting section when the tutorial is done. Any tangential information that you might have left out while describing the steps can be placed here for the reader.
6. FAQs: At the end of your article, add a Frequently Asked Questions section so that you can address some common questions that you might encounter. This is also a great place to guide your readers to other articles covering similar topics.

Headings and Callout Boxes

1. All steps should be under proper Headings and Subheadings that match their context. If your article contains two or more tutorials, each section should be under its own H1 tag, with the steps under an H2 tag.
2. All your steps should be under a distinct H1 tag that separates the tutorial section from the introduction, conclusion, troubleshooting and FAQ sections.
3. Callout boxes should follow the guidelines set by the Tech Writing 103: Technical Difficulties article. In summary, use callout boxes sparingly to provide relevant information during a step without breaking the flow of the tutorial. Any important content in a step not directly related to an action in the tutorial makes great callout box material.

Final Steps

After you are done writing your article, don't forget to check it using the guidelines provided by Tech Writing 201: Content Standardization and Fluency. In essence:

1. Check your content in the Hemingway App and make sure it scores as low as possible on the readability test.
2. Check your content in Grammarly to find grammatical errors and fix the ones you think are relevant.
3. Check your content for Plagiarism in Grammarly and make sure it does not score more than a 5% plagiarism score.

Finally, submit your article to your editor for publication once everything is done. Awesome!

How To and Tutorial Article Template

Below is a template to help you with writing tutorials. You can copy and paste it to your editor of choice and fill it in to help with formatting.