Tech Writing 204: Troubleshooting and Tips & Tricks

Below are the requirements and guidelines for Troubleshooting and Tips and Tricks type articles.

Requirements

• Word Count: 500-800 words
• Image Usage: Recommended

Image Usage

• Your images must be under one of the following licenses: CC0, CC1, Public Domain, Apache2, or MIT.
• Brand Images and Screenshots of said application can be used if the developer has made such usage public domain.
• 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.

Formatting Guide

The formatting guide for Troubleshooting and Tips & Tricks articles is shown below.

Troubleshooting

A troubleshooting article's purpose is to solve a problem that might be encountered by a user. It will generally lay out a problem within a certain software or workflow and provide an ample list of solutions to the problem in question.

Such an article- should provide clear examples, and the best possible solution for the problem displayed. If a perfect solution does not exist, such facts should also be mentioned in the article if possible.

An article on troubleshooting is recommended to contain the following sections.

1. Introduction: You should briefly introduce the software you will be using and outline some common problems that a user might face. You should also mention your level of expertise in using said software to give your reader an idea of what level of troubleshooting help they will be getting through the article.
2. Problem Description and Causes: Continue the article by demonstrating the problem using screenshots or text-based examples. Once the scene is set, outline the probable causes of the issue to provide more insight into the problem-solving process rather than just listing solutions. Also, a good practice is to label each problem's H1 tag with the Problem: appendix, which will help the reader navigate the article better.
3. Solutions: Speaking of listing solutions, try to cover different types of solve cases for the problem in question. A problem might have multiple solutions that achieve similar results, but the writer should always try to present a multitude of solutions such that the reader is not stuck in case one of the provided solutions doesn't work. If there is only one solution, explain it in detail and mention how to avoid such problems in the future.
4. Conclusion: Conclude your article by showing the fixed solution and mention any relevant things the reader should know. It is also a good idea to summarize all the problems you covered and add a shorthand solution for those who just want to know how a specific problem was fixed.

Tips & Tricks

A Tips & Tricks article covers the usage of a single piece of software and highlights key shortcuts and features that might not be obvious to new users. Articles like this are useful for people who are learning a process that you might already be familiar with. It is a good idea to go in-depth about the tools, and specific advantages of the software as a lot of ground can be covered that way.

Tips & Tricks articles should be formatted as follows:

1. Introduction: Begin your article by describing the software you will be using. Any background of your experience with the software and your proficiency level should also be mentioned to denote the skill level of the article.
2. Tips Showcase: Since a tips and tricks article will cover many bases and shortcuts of an application, you should clearly separate all separate tips into a separate H1 tag. If you are showing how to use shortcuts, make sure that they are formatted correctly, i.e. Buttons in Bold and use shorthand key names if possible. For example, Ctrl + Shift + Tab opens the Task Manager in Windows. Also, clearly demonstrate what each tip and trick does and provide use cases for everything relevant. You may add any number of such headings as desired.
3. Conclusion: A conclusion is not strictly necessary for an article type like this, but it is always a good idea to conclude the article by asking the reader whether they found the article helpful or not.

Headings and Callout Boxes

1. All separate products and sections should be under proper Headings and Subheadings that match their context. If your article contains two or more cases or products, each section should be under its own H1 tag.
2. If you are showing Similarities and Differences, Pros and Cons, or describing use cases or tools, it's a good idea to separate those into different H1 tags as well.
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 article. Any important content not directly related to your points about a case or product is 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. Great Success!

Troubleshooting and Tips & Tricks Article Template

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

Troubleshooting:

Tips & Tricks: