Good afternoon all!
I know I’m not the world’s foremost expert on grammar and punctuation. For writing mostly-private things such as code or instant messages, if you can’t string together a thoughtful sentence it’s not the end of the world.
That world changes when you’re talking or writing publicly. When I was in the early days of my career, you wouldn’t see a memo, email, or presentation-level document come out that hadn’t been worked over for a week by a person who had worried about it enough to dig out an ulcer. Today, you wouldn’t believe what I see out there that passes for a document suited for public consumption – much less client presentation.
I know reading my blog here you may be thinking, “hey Pot, I’m Kettle!”. I make a good effort to go back over my work for glaring errors, but I’m honestly not too worried if I use a runon sentence (like this one!), if I could have used a semicolon in place of a comma, or I should have used 9pt Helvetica instead of 10pt for a 3rd level bullet point.
What I do is not defined with WHAT I CAN DO – it’s defined by WHAT I LEAVE BEHIND. How I speak face-to-face or over the phone is forgotten, but what I write down stays forever. No one is going to remember the cool code trick you did to make a screen pop work flawlessly – they’re going to remember it was you who coded in “Accoutn” instead of “Account” in that popup’s title bar.
Technical documentation is no different. I’ve seen technologists write REAMS UPON REAMS of documentation thinking that they’ve created this sort of holy grail that has every single thing that someone may ask. On the flip side, I’ve seen some people write up one page – or even don’t document at all. Not a single one of those approaches are the right answer – just as much as they aren’t the wrong answer. Sometimes you need reams, sometimes you just need one page – the most important thing that people often overlook is HOW THE INFORMATION IS PRESENTED. Is it logically laid out? Is there a table of contents? Is there a revision history? Are there simple things like header/footer/page numbers? Word Processors (in my example following – MS Word) give you so many tools to create a greatly impactful and relevant document, but it’s so amazing how many people completely ignore them. Learn Word (or OpenOffice) people!
A little humor to close out the post…
It’s the little things…and I correct when I can / is appropriate, but I saw a web comic a while back that always make me laugh. Matthew Inman, or “TheOatmeal” as he calls himself, puts together some incredibly hilarious comics. He has an entire section devoted to this topic! I revisit his site frequently for a laugh, but I do actually use his site to CHECK MY GRAMMAR if I think it looks weird…just to be sure. =)
Good stuff – link: http://theoatmeal.com/tag/grammar