Julia

I think photographs are more detailed, but animations can be more demonstrative. Ultimately, we're a highly visual culture—we need effective visuals in technical documentation to really solidify meaning. So yeah, use animations!

This is, honestly, a great question. And there's no right answer to this one. Certainly, one of the downsides to cooperative, collaborative writing is that you sometimes have too many opinions about a document—and sometimes those opinions conflict. Certainly, if the feedback you're getting is technical, I would privilege comments made by your technical experts. Remember, though, as a writer, you're the expert on style, audience, and organization. If people have two different ideas about how to present the same information, pick the idea that you think better relates the material to your audience. If you're not sure what works better, try both suggestions—see which version turns out better. When it comes to style and content, the final say in the matter should be up to you, the writer.

It depends on how complicated or delicate the procedure is—and how versed your target audience is with the procedure. For example, at iFixit we write repair manuals for consumer electronics. Our guides and manuals are designed so novices can easily use and understand them. Naturally, we don't want our readers to damage any of the delicate components in their iPhones or their MacBook Pros. So, we supplement our textual instructions heavily with pictures. Essentially, every time the repairer's hand moves, there is a picture to document it. We need the reader to see just how a component slides off the connecter, or how a tiny tab swings open. Without that level of detail, novice repairers might just pull a component off the motherboard and completely ruin their device. Of course, not everything requires that much visual explanation. A general rule of thumb: Use pictures when words won't suffice on their own, and your text needs that extra level of visual clarity.

Humor is a matter of style, and style should be fairly consistent from doc to doc. But I actually love humor in technical writing, because I think that humor (done well) is a great way to make something memorable. Make someone laugh unexpectedly, and they'll remember it. Humor is engaging—and when you're writing about dry topics, finding ways to keep the audience engaged is half the battle. You certainly can go overboard with humor, though. And unless you have a natural flair for jokes, it can be genuinely hard to write funny material (force the joke, and you kill the joke). As always with writing, it's a balancing act. Mackie, by the way, is really good at balancing information, instruction, and humor in their product manuals. I'd look to them for a good reference.

Personally, jargon is one of my pet peeves. I think it's often overused, and that buzzword-type jargon loses its meaning quickly. Still, jargon certainly has a place in writing—specifically, it signals to other experts that the writer is already a member of the same technical community. And yes, you get a token of respect for knowing words and concepts that other experts freely use. That said, writers very quickly forget that the words they are using are, in fact, jargon. We forget that jargon has no meaning to an outside audience. So if you're writing training material or documentation meant for the public, then jargon very quickly gets in the way of meaning. And it very quickly becomes a frustrating reading experience for the reader. If you're writing to experts, sure—feel free to use jargon. If you're writing to anyone else, I'd urge you to examine the assumptions you make every day about word choice—and who those words are meant for.

That's really a question about your audience, and what they know. The first step to any technical writing endeavor is examining the audience that the writing is meant for—understanding what they know and what they don't know. Of course, if your writing is designed for a general audience, then you could have a wide range of technical abilities—so there's a bit of a challenge there. That said, it's hard to make technical writing "too easy." And people usually aren't insulted if they can understand the process you're describing quickly and well. Of course, if IKEA instructions are any indication, the sorts of things that you think are easy could feel very challenging to someone else. Try to produce something that everyone in your intended audience's technical spectrum—from the novice to the technically astute—can understand and reproduce. In 10 years of writing with iFixit, no one has ever told us they felt insulted because our repair guides underestimated their technical capabilities.

Good question, Shaun. In my experience, it's actually really difficult to write to a fifth grade level. When it comes to technical writing, our sentences are naturally a little more complex. I'd say that you should shoot for about a 9th-grade level—but it all depends on audience, and their unique needs. As a writer, though, I'm much more concerned about drastically over-complicating my writing than I am over-simplifying my writing. Technical writing is notoriously hard to read—and that's the bigger pitfall.

We are making some alterations to the way category pages are structured. The object of any category page is to make it easy to find the guide you’re looking for. But as content grows, your site might contain thousands of guides. That’s a lot to sort through. Our new design will make category pages easier to navigate and nicer to look at. All of the information on any Dozuki site is organized into a hierarchy of information. It’s helpful to think of this hierarchy as a family tree, with parents and children and grandchildren: So, in the example above, “artist” is the parent category, “painter” is the child category, “impressionist” is the grandchild category, and so on down the tree. The new category pages use this hierarchy to get your users to the guide they need quickly. Category pages are now more detailed and more structured. As before, they display the parent category and links to its associated guides. Now, pages also display child and grandchild categories, as well as links to their respective...