Milestone 1: Overview

In Milestone 1, you will create a troubleshooting page for your device. A troubleshooting page helps your readers diagnose what is wrong with their device and points them to the correct guide.

Checklist

You are finished with this milestone when your troubleshooting page:

  • Has the correct title
    • Excludes extra descriptive words, such as "laptop," "printer," or "camera"
    • Includes the word "Troubleshooting" in the page title
    • Uses proper spelling, punctuation, and the right device name
  • Is properly formatted
    • Headings are user-experienced symptoms
    • Subheadings are possible causes of those symptoms
    • Solutions are explained in short paragraphs
  • Explains the symptoms of each issue in detail so that a user will know if they are having the same problem
  • Discusses all of the possible causes of each issue in depth
  • Outlines the necessary steps a user must take to return their device to working condition
  • Includes a table of contents
  • Includes placeholder links to applicable guides (actual guide links are added after completing Milestone 3)
  • Incorporates all feedback from the iFixit technical writing team

Email Us When...

...your troubleshooting page is complete. We’ll be happy to look it over and offer feedback!

Overview

A troubleshooting page helps users diagnose a damaged device. Your troubleshooting wiki should list common symptoms of a malfunctioning device and describe possible causes and solutions, listed in order of probability.

Any number of things may be wrong, thus complicating problem diagnosis. The Lenovo Essential G560 troubleshooting page, for example, lists several symptoms, including not powering on, sticky keys, and video distortion. Often, several potential causes exist for any particular symptom.

It is important that your troubleshooting information be as accurate as possible. Writing a good troubleshooting page requires a substantial amount of research—scouring forums, product manuals, and enthusiast sites. It should comprise the most common symptoms people encounter with this device and what solutions have worked for people in the past. It is very important that a troubleshooting page be robust and descriptive.

Example Pages

The following examples from past projects give a good idea of what your completed troubleshooting page should look like.

 

Research Strategies

Thorough research is a crucial step in understanding what issues users may experience with their device. Remember, you’re helping real people keep as much stuff out of landfills as possible! 

Here are some research strategies for an example device (Canon PowerShot SD900):

  • Google search "Canon EOS Rebel T5i won't turn on,” "problems,” "repair,” etc. If you find repair-oriented or parts sites, the parts that they sell will clue you in to what people need to replace.

  • Use enthusiast sites like this one—they will pop up in searches. Browse through them to get a feel for common problems.

  • Feel free to research similar devices on iFixit.com for reference.

  • Beware of Fixya. Fixya has some information, but confusingly mixes in other information from completely unrelated devices. Use information from this site with caution.

  • Some devices have little to no repair information about them (either because of manufacturer frugality, or simply because no one has bothered to try and fix that device yet). Don't let this hinder you! Rather, use common sense and think of some problems that could possibly arise, i.e. not turning on, sticking keys, or black screens. You can also research problems with other, similar devices; odds are, some of them will apply to your device as well.

Create A Troubleshooting Page

Page Layout

Your troubleshooting information will appear on a wiki page with specific formatting guidelines.

The basic layout of each troubleshooting topic should resemble the following format:

  • Heading phrased as a user-observed symptom

  • Description of the symptom in italicized text

  • Subheading phrased as a possible underlying cause

  • Solution of how to complete the repair

 

When formatted correctly on your wiki page, it will look like this:

Creation

When creating your troubleshooting page, it's best if only one team member edits the page at a time. If more than one person attempts to make changes simultaneously, they may unknowingly overwrite each other's work.

To create a troubleshooting page:

  • Click here to start a new page.

  • Select "Wiki" from the list of options.

  • Enter "[Your Device Name] Troubleshooting" into the title field.

    • Do NOT include the device type or generic terms such as “laptop,” “cell phone,” etc.

    • If your device was provided by iFixit, copy the name directly from the white iFixit label on the device.

    • For all other devices, write the name exactly as it appears on the manufacturer's website or in the device's official documentation. If your device is known by more than one official name, stick with the most common one (Google Trends can be helpful here). If you're not sure, drop us an email at techwriting[at]ifixit[dot]com!

    • Be sure to use correct spelling, capitalization, and spacing when creating your troubleshooting page. For instance, the 's' in Cyber-shot is not capitalized, while the 's' in PowerShot is.

Formatting

When you create a troubleshooting page, you’ll be directed to a page like the one below:

Screen Shot 2019-03-26 at 5.23.24 PM.png

 

To create a header or subheader, highlight your text and click on the “¶” to access the drop-down menu. From there, click on “Header” or “Subheader” (while your text is still highlighted) to create the appropriate heading.

image1.jpg

After you create your header, you’ll need to include an italicized one-sentence description of the symptom. To italicize your text, highlight your text and click on the “I”.

When you revisit your Troubleshooting Page after creating your guides in Milestone 3, make sure to add the links to your guides in your solutions. To add a link to a guide, highlight your placeholder text and click on the “🔗” symbol. From there, paste the URL of your guide into the text box and click “Confirm Link.” You’ll notice that the text you highlighted will turn blue.

When you're finished, be sure to check the box labeled "Show table of contents?" at the top of the Edit page. This automatically creates a linked table of contents on the left side of your page using the headings and subheadings you've just defined.

Princess Leia: I hope you know what you're doing.
Han Solo: Yeah, me too.

Do you know what you’re doing?

Better review those technical readouts of the battle station—or at least the guidelines in the milestone—before you find your grade plummeting into the Great Pit of Carkoon to be eaten by a sarlacc. Email us at techwriting[at]ifixit[dot]com when you have a finalized draft of your troubleshooting page, and we’ll let you know when you’re ready to make a run on the Death Star, or, Milestone 2.

HOLD IT! LET'S REVIEW THE CHECKLIST... Keep in mind, you're still required to email techwriting[at]ifixit[dot]com to ask for feedback. *Asterisk indicates required field.
Is the troubleshooting page title capitalized and punctuated correctly with no extra descriptive words, such as “laptop,” “printer,” or “camera?” *
Is the word “Troubleshooting” included in the page title? *
Is the troubleshooting page formatted so that headings are user-experienced symptoms, subheadings are possible causes of those symptoms, and the solutions are explained in short paragraphs? *
Are all of the above sorted in a table of contents on the left side of the page? *
Are the symptoms of each issue explained so that a user will know if they are having the same problem? *
Are all the possible causes to each issue discussed and explained in depth? *
Does the page outline the necessary steps a user must take to return their device to working condition? *
Are placeholder links to relevant guides provided? (Circle back and replace these with the correct guide links upon completion of Milestone 3.) *
Did you email a link to your troubleshooting page to techwriting[at]ifixit[dot]com? *