Checkpoint 2: Overview
You are finished with your guide text when it:
- Is easy to understand and follow for an audience with an average to below-average technical background
- Is free of verbose and muddled directions
- Avoids vague language and outlines the procedure with adequate detail in each of the guide steps
- Correctly identifies key tools and components being used in the procedure
- Is free of major errors in grammar, punctuation, and spelling
- Includes a brief summary and a descriptive introduction outlining the procedure being performed
- Notes the head types and lengths (in mm) of every screw in the guide
- Has an appropriate title
You are finished with your guide details when they:
- Have a completed Details section, including the difficulty, time required, and tools
- Have correctly colored markup in guide photos and use appropriately colored bullet points to match them
- Make proper use of the Note, Reminder, and Caution bullets
Email Us When...
...you complete the first draft of your guide. We'll be happy to offer feedback and help you get your guide ready for prime-time!
In this checkpoint, you'll add step-by-step written instructions accompanying your photos to create a simple and straightforward guide that anyone can follow.
Your completed guide should contain the following:
- A title and brief (1-2 sentence) summary
- A descriptive introduction
- Estimated difficulty and time required
- A list of any required tools
- Step-by-step instructions written in clear, complete sentences
- An accompanying photo or photos to demonstrate each step
- Visual markup (where appropriate) highlighting key areas of the photos, matched to color-coded bullets in the text
Keep in mind that your final guide will have a global audience, so you shouldn’t rely on the text alone to communicate key information. Your readers should be able to complete the guide using only the photos, or only the text. Both the written and visual portions of your guide should work together, yet be able to stand on their own.
While Working On Your Guide
Don’t work on the same step at the same time as your teammates. It's okay for multiple team members to work on the same guide at the same time, so long as each team member works on different steps. If more than one team member tries to edit the same step at the same time, they may overwrite each other's work.
- Create a new guide by clicking here.
- Under “What type of guide is this?” choose “Technique” or “Replacement” from the drop down menu. (Most Fast Fix projects will either cover a specific repair technique for a broken item or the replacement of a broken part.)
- Give your guide a short, descriptive title. For example, you could write a technique guide entitled "How to Patch a Flat Tire" or a replacement guide entitled "Skateboard Wheel Replacement." (If there's already an automatically generated title or partial title such as "Fast Fix Replacement" in this box, go ahead and change it to something more descriptive.)
- Write a short summary for your guide. The summary is used in search results, so keep it brief (one or two sentences), and include any terms or phrases that your readers would be likely to search for. A good example of a summary might be, "Fix a hole in your jeans by sewing on a denim patch."
- Click the “Show More” button. This brings up some additional fields for your guide.
- Write a short introductory paragraph for your guide. The introduction should contain any background information a reader would need before they begin. Think about what you would tell a friend before doing this guide: any special requirements, hazards, why this fix might be needed, etc.
- Add the "Fast Fix" tag to your guide. In the Tags section at the lower right, fill in the phrase Fast Fix—and be sure to click 'Add' then 'Save Tags.'
- Leave the “Flags” section alone for now. At the bottom of the page, you may see some auto-generated "In Progress" or “Student In Progress” flags that mark your guide as being part of a student project. It's okay to leave these alone for now.
- Click “Save.” Congratulations! You’re ready to start your guide and will now be taken to the Edit page for the first step.
For each step in your guide, you’ll add both written instructions and photos demonstrating those instructions. Let's go over photos first.
Preparing and Uploading Your Pictures
Before adding pictures to your guide, you can use Photoshop or other software to lighten up or crop them so that they look better.
- Please do NOT use Photoshop to add markup to pictures. Instead, use iFixit's built-in markup tool (more on this below). This way your teammates and collaborators can edit the markup, whereas Photoshopped markup is permanently attached to the picture.
- Keep your pictures as large as possible in terms of resolution. If a picture is 4000 x 3000 pixels in size, so be it! We love large images.
- Click on the camera icon to upload a photo. This brings up your personal media manager, where you can manage your existing photos and upload new ones.
- Crop your photos if necessary. Our software will prompt you to crop your photos to a 4x3 aspect ratio using the built-in tool. 4x3 is standard throughout the site; no other formats are permitted.
TIPS FOR WRITING GREAT TEXT
Technical writing is a little different from what you've done in other classes, so we created this "cheat sheet" of sorts to help prevent you from committing any word crimes. (For writing more advanced guides, such as “How To Use Your Samurai Sword For Zombie Defense,” check out the Tech Writing Handbook.)
- Gear your writing towards an audience with little technical knowledge. Remember, you might know all about this fix, but your audience doesn't (yet). Try to avoid using complex jargon or technical terms that could be confusing for a reader doing the fix for the first time.
- Use the active voice. You're telling someone what to do in your guides, so tell them something to do. Simply stating that a component can be removed is passive and weak.
- Be clear and descriptive, yet concise. Writing instructions that people actually want to read requires finding a middle ground between vagueness and verbosity. Read your own text out loud to yourself. You'll quickly have a feel for whether or not you've found the happy medium.
- Write complete sentences. Don’t let those bullet points deceive you—proper grammar is critical to a clear and comprehensible guide. Remember to include all punctuation, including commas and periods.
- Use articles like “a,” “and,” and “the.” As a reader, articles tell your brain that a noun is coming. When it comes to technical writing, it's commonplace to see articles dropped completely—but for those of us who aren't used to technical documents, this makes for rough reading. Gear your writing to a general audience, and use articles. We not robot, after all.
- Identify parts and tools correctly. This might sound obvious, but make an extra effort to use the correct name for what you're describing, so that you can write clear directions.
- Keep it simple. Avoid writing obvious steps like “Remember to keep track of your screws,” or “Locate component X.” Your readers will quickly tire of reading tedious or repetitive instructions, but they’ll thank you for text that is accurate, to-the-point, and concise.
- Your first step should dive right in to the procedure. There's no need for a step showing the tools necessary for the Fast Fix. Instead, make sure to list the necessary tools under the Tools section of your guide.
Once your photos are in place, you can use iFixit’s markup system to highlight the location of any important items in your photos, such as screws or connectors.
- To add markup to an image, first click the gear icon on the image thumbnail, and then click “Markers…”
- Start off each step with red markup. Use additional colors only if there are more items that need to be marked up in the same step. Use them in the order they appear (red, then orange, then yellow, etc.). (Exception: If you’re marking up a red object—or any other color that doesn’t provide good visibility—feel free to skip to a color with better contrast.)
- Don't add lines or arrows. The markup editor can create lines and arrows, but you should not use them for this project.
- Don’t overuse markup. Only add markup where it is necessary to point something out that is not otherwise obvious in the image. In many cases, a well-composed photograph that is centered on the action won’t need any markup at all.
- Here is an iPhone 4S repair guide that shows some good examples of how to use markup.
Guides on iFixit are written in a step-by-step, bullet-point format.
- Each bullet should represent one idea or action.
- By default, each step starts off with a single black bullet.
- You can use up to eight bullets per step if needed.
- Some additional controls are found at the bottom of the window:
- Indent the text to the right (or left)
- Add a new bullet below
- Delete the current bullet
Click on the bullet to select additional bullet colors or types.
- Use a colored bullet to match the color of any corresponding markup on the image.
- Use colors in order. Just like with markup, when using colored bullets, always start with red, then progress to orange, yellow, etc. as needed.
- Use special bullets as follows:
- Caution: Warns users of something potentially hazardous to themselves or the device.
- Note: Provides information other than instructions which may be helpful in completing the repair.
- Reminder: Provides reassembly tips (anything that differs from simply reversing the existing steps).
- Use special bullet types sparingly. Constant use can overwhelm your readers, making the special bullets ineffective.
- Don’t write the words “Caution,” “Note,” etc. when using special bullets. The special bullets already alert the reader to pay extra attention.
Clicking on the Details tab at the top of your guide’s Edit page gives you access to some important fields. These fields are critical to help people be prepared and empowered to fix their device. Before you finalize your new guide, be sure to complete the following:
- Estimate the time required. Keep track of how long each of your repairs takes (not how long it takes to write the guide), and provide an estimate for your readers. This should be the total time from the start of the repair to the moment it's finished. Remember that you’re writing for a non-technical audience, so it’s best to be a bit conservative with your estimate.
- Estimate the difficulty level. Click on the drop-down menu for an explanation of each difficulty level, and select the most appropriate one. For example, “Easy” requires minimal disassembly and common tools, whereas “Difficult” requires specialty tools or skills such as soldering.
- List any required tools. If you’re unsure what a tool is called, try to find out.
Hold up there, speedy!
Slow down and make sure you’ve met all the project requirements. This is your last checkpoint for the project and you wouldn’t want to pay a heavy fine in terms of your score for zipping by. Send us an email at techwriting[at]ifixit[dot]com when you think you’ve got a finalized draft of your guide. We’ll let you know when you’re ready to move on—and we’re a lot nicer than the fuzz.