How to Make an Awesome Guide

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!

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.

Pictures and text should augment each other. Additional pictures can be used to supplement textual explanations, and vice versa.

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!

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.

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?).

Crosslinking is your friend. Link anything and everything you can to relevant resources elsewhere on the site.

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.

Adding more pertinent information gives authority to your repair manual.

People will not use your repair manual if they cannot understand what you're talking about.

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!

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.

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.

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!

Use step titles sparingly. Adding prerequisite guides correctly will automatically add an appropriate navigation structure -- so step titles are unnecessary in most circumstances.

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.

We're here to help each other learn how to fix stuff. Reserve your political views and other such opinions for the appropriate place.

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.

Only upload photos and text that you own or have the rights to.