I downloaded a whitepaper the other day from a company I’d never heard of.
I’ll call them “Company X”. I’ve only had four coffees today, you see, and I can’t get that imaginative over a company that introduced itself so awfully to me.
You see, having never met or communicated with anyone from this company before, and having never heard of them before, they introduced themselves to me via their documentation.
It wasn’t a very good introduction.
Once, a long time ago, I was introduced to someone who obviously had a few nervous twitches when it came to meeting new people. In the 5 seconds between him being introduced to me and extending his hand to shake mine, he scratched his bum, blew his nose, checked his handkerchief and coughed.
Technically it was an introduction I’ll never forget.
This whitepaper was almost like that introduction.
First page: Company logo dropped into the PDF as a very low-res bitmap. Very grainy. This was right beside a vendor logo (the whitepaper had been co-written) which was a proper vector graphic and scaled appropriately. So it only served to exacerbate the poor look of the company logo.
Next relevant page: Table of contents. That should be easy enough, but no … not really successful:
A bit further on: General list of technologies and vendors referred to in the whitepaper:
Then there were tables that looked like this:
Note – I’ve redacted content to blank out the company and vendor associated with this whitepaper. What I’m referring to in that table is the formatting. Why is there a row break after the first line for item (1), but it continues into a row underneath? Why are items (2) and (3) mostly in the same row, but the final line of item (3) extends into the next row?
The technical content of the document seemed to be perfectly correct and useful.
Yet, it was presented in such an amateurish style that here’s the impression I got of Company X:
- They don’t proofread their work (Error! Bookmark not defined.)
- They don’t take pride in their company (the sloppy logo work);
- They don’t care for presenting their best face (the awful font and kerning issues);
- They have the attitude of “Good enough is still good, right?” (the terrible table formatting).
End result? If this were a local company to me (thankfully, they’re not), I’d be unlikely to want to deal with them or engage their services. If I did, I’d be factoring in additional time to cleanup their sloppy work and check to make sure they did everything they were engaged for.
Of course, that’s just my impression. It could be the truth is totally the opposite of my first impression of their company.
But as the saying goes – first impressions count. It’s not just a saying – it’s often grounded in measurable fact. We’d like it to be otherwise – that the logical, rational parts of our brains always exert complete control, but that’s not always the case. Just watch Simon Sinek’s TED presentation on “How great leaders inspire great action” to understand how much pull the limbic system has on us.
That’s why I get passionate about documentation.
That’s why you should get passionate about documentation if you’re in IT, too. It’s not an adjunct or a “last minute” activity – it’s something that should be done with as much pride and care as the technical work itself.
Every document should be written with two points in mind:
- To address the immediate purpose of the document.
- As a potential introduction to another reader later.
The first point is what we all do when we’re writing documentation on a day to day basis. The second point is more ephemeral, less easy to remember – yet potentially of much greater consequence. A document may sit unread for 2 or 3 years after it was first authored before it is suddenly discovered by someone entirely new. Someone who hasn’t dealt with your company. So when your document introduces your company for you, do you want it to do it properly, or risk that it’ll scratch its bum, blow its nose, check its handkerchief, cough, then extend a hand to shake?