Writing Documentation Like a Real, Live Person
July 17th, 2008When you’re reading over your documentation, does it sound like a robot wrote it? I’m sure mine does.
One of the benefits of starting on a new project is that I can try out new things. This time around, one of those things will be a more relaxed style using contractions. I thought of this because when I’m writing other things, such as a journal entry or creative piece, I tend to use contractions. They’re a natural part of speaking. So as I was writing some help, I started to include some contractions without even thinking about it.
I caught myself, but I asked Tom’s opinion on the subject. He’s in favor of using contractions in documentation, making the point that when you have a frustrated user, he or she is going to want to talk to a person, not a robot. Therefore, make your documentation sound like it comes from a real person.
Something like using contractions is so simple, but I got the idea from somewhere that contractions are illegal in formal writing (must have been in kindergarten—I think that’s where I learned everything that I can’t remember where I learned it). I’m going to let myself write more naturally and see if that results in more user-friendly help.
Then I, with Pinocchio, will be able to say, “I’m a real boy!”
Subscribe to the Journals
July 17th, 2008 at 5:48 pm
It does sound a bit stilted, does it not, when there are no contractions?
However, the reason that most folks have stopped using them is because of translatations and localizations, and because those who have English as a second/third/fourth language sometimes find it harder to comprehend. I try to rewrite around them whenever possible.
July 18th, 2008 at 8:53 am
I have read that understanding contractions requires a reading level higher than that which is average in the US right now. Reading levels used to be around the 10th grade. They are now around the 8th grade, and falling.
July 18th, 2008 at 4:50 pm
I’m definitely not going to go out of my way to use contractions, but rather to be more conscious of places where they could be appropriate. This new project isn’t going to be localized, so that removes one complication.
I find it very surprising that contractions are considered at a high school reading level; it seems counterintuitive, since contractions are informal. Craig, do you remember where you read that? I’m sure I heard the same statistic about the 8th grade, probably in my reading theory class in college. It’s sad, really. I think good reading skills are a matter of getting books in kids’ hands at a very early age, but that’s a soapbox for another time (and venue, perhaps).
July 18th, 2008 at 10:40 pm
[...] yesterday my colleague Ben was asking how I felt about the use of contractions in help. Contractions? We’ve moved far beyond [...]