How to Make an Awesome Guide
Use these guidelines to make really great repair manuals that will help people fix things!
- What to do
- Take awesome photos
- Augment pictures with text
- Be descriptive
- Use pictures to orient the reader
- Minimize background info
- Crosslink heavily
- Stay relevant to the topic at hand
- Be informative on the subject
- Be simple, not loquacious
- Use the appropriate bullet marker
- Add reassembly notes
- Include diagrams
- What NOT to do
What to do ¶
Any guide is a thousand times better than no guide at all. The following are not rules, but guidelines. Even we sometimes forget to follow all of them, or go back and re-edit something if needed. We know we're all human, and that we make mistakes. These guides will get better over time, so don't feel like everything has to be done perfectly the first time. Be the pioneer!
Take awesome photos ¶
Excellent photos are the number one thing that will draw people to your repair manual. Taking excellent photos is totally possible with inexpensive equipment. Take some time prior to your shoot to study our photo tutorials.
Augment pictures with text ¶
Pictures and text should augment each other. Additional pictures can be used to supplement textual explanations, and vice versa.
Be descriptive ¶
Vague words like "thing," "part," and "stuff" lead to ambiguous repair manuals. If you don't know what something is called, do your best to identify it by Googling or asking someone. Gadgets may have several intricate internal parts -- calling a part "this thing" doesn't help anyone!
Use pictures to orient the reader ¶
The orientation of the object should remain the same as much as possible throughout the guide. The reader will be able to identify his or her location on their own device with greater ease. If you do rotate the object, include a statement such as "Flip the device" or "Rotate the device 90 degrees clockwise" to help the reader do the same.
Minimize background info ¶
A little background info is great: why you're doing this, who stands to benefit from the guide, what people need to do to prepare for the guide. However, leave it at that -- most people on the internet shudder at the thought of reading a book before repairing something (when's the last time you read the user manual that came with your TV?).
Crosslink heavily ¶
Crosslinking is your friend. Link anything and everything you can to relevant resources elsewhere on the site.
Stay relevant to the topic at hand ¶
As much as we love stories of your great-grandma putting ice cream in her purse (true story!), there's an appropriate setting for such stories. The middle of a repair manual is not it.
Be informative on the subject ¶
Adding more pertinent information gives authority to your repair manual.
Be simple, not loquacious ¶
People will not use your repair manual if they cannot understand what you're talking about.
Use the appropriate bullet marker ¶
You can create a ton of confusion by using bullets inappropriately. Donate a second and read up on each bullet's meaning before using it. When in doubt, use the default!
Add reassembly notes ¶
The device may not require reassembly notes if it's simple enough. But reassembling it may also require special instructions. For example, disassembling a MacBook LCD display is pretty straightforward. However, if you don't route the wires properly during reassembly, they won't reach their connection points on the logic board. Readers will thank you kindly if you include little tidbits to help them reassemble the device once it's in pieces.
Include diagrams ¶
Pictures and text can only go so far in some circumstances. Adding a diagram or two (and uploading it as a picture) will certainly help the reader figure out how to repair it.
What NOT to do ¶
Don't overuse markup ¶
Adding too much markup will make the picture look freakishly un-inviting for the reader to view. Add just enough to identify what you're talking about, if you feel markup is needed at all. If you're adding more than 4-5 bits of markup, you may want to split the work into multiple steps. When in doubt, look at some iFixit guides!
Don't overuse step titles ¶
Use step titles sparingly. Adding prerequisite guides correctly will automatically add an appropriate navigation structure -- so step titles are unnecessary in most circumstances.
Avoid using the first person ¶
There's no "I" in team, and there shouldn't be any in your writing. You have a more authoritative tone of voice by not using statements such as "I did this" in your manuals.
Don't force your opinions onto others ¶
We're here to help each other learn how to fix stuff. Reserve your political views and other such opinions for the appropriate place.
Don't use passive voice ¶
Be direct in your instructions to the user. Do not fall in to the "It is" trap, and instead use verbs to convey what you're trying to say.
Don't upload content that you don't own ¶
Only upload photos and text that you own or have the rights to.