Saturday, 30 April 2016

In Defence of Documentation

In the past I've written about the benefits of documentation, and documentation ROI, and how some people see documentation as a cost rather than a value, and various other short form essays on documentation issues.  But none of these really get to the heart of what I want to say about documentation, they just skirt the outright point.

I want to defend documentation, both as a profession and as a business necessity.

More than that, I want to go on the attack, to shout loudly and widely that what we do is important and valuable and good, that without documentation your knowledge is entirely transient and dependent solely on your ability to keep your staff working for your company, because everything that customers need to know is locked in your peoples' heads.  I want to corner you and force you to acknowledge that there is no information about your products that shouldn't be written down in a clear and consistent manner, that customers are always better off with great documentation, that there is no area of your business that couldn't lower costs and increase efficiency with just a little sensible documentation of the things that are important.

I watch and I grieve as companies choose to value only those things they can easily measure, whilst doing everything they can to reduce those things which have a value that can't be entered as a number in a spreadsheet.  But of course, strategic thinking, or planning, or playing golf with a customer, these are not activities with a measurable value.  But they are in the MBA play book, and the Sales handbook, and, dammit, everyone knows the value of these things, right?

It is odd how these activities, which so many companies put great store in, are never the activities that are cut during the hard times.  No, it's things like documentation, concrete deliverables that add real value for the customer base, that are cut.  Not enough lines on the spreadsheet, you see.  Besides, what's important is sales, and they sell dreams and visions.  How does your documentation help them sell?  No, no, no, far too prosaic.  No-one dreams about having great documentation!  People want to believe in our products!  So we take them onto the golf course and spin our tales of efficiency savings and cost cutting and the awards they could win for their implementation, and whilst they're misty eyed about their future prospects we shake their hand and tell the guys back at the office to fax the paperwork over ASAP.  What's that?  We don't have enough people to implement or support it?  We've sold something that hasn't technically been developed yet?  Oh well, don't worry, that's for the business to sort out.  Now get a move on, we've got dinner with another potential client tonight!

This short term, pipeline-obsessed mentality is absolutely fine within the sales team, because that's their job.  But a sales mentality is a world away from what real leadership of a company looks like.

Leadership looks at much more than the numbers in a spreadsheet.  Leadership sees the intangibles like quality, integrity, reputation.  It sees the long term benefits of investing in the undersold professions that provide the difference between middling and market leader.  It disrupts not through marketing campaigns but through old-fashioned concepts like "investing in staff", "trusting specialists" and "research".  Great ideas that don't come from the leadership are treated as things to be encouraged for the benefit of the company, not strangled at birth in case they threaten the comfy chairs. 

These leaders spend money on the boring things like documentation, QA and testing, things that don't have a simple relationship to the balance sheet.  Why?  Because they know that a company that makes products that are unreliable, user-unfriendly and poorly documented will only sell to the ever decreasing market of those people who haven't been disappointed by said company before.  And meanwhile the company will have to throw more and more money at salespeople and marketing experts to make up for the deficit in confidence that customers have in the products being pushed at them.

What technical writers do is not cool.  It's not hip, trendy, sexy, or chic.  It's far more valuable than any of those things: It's important.

If you don't get that, why would a technical writer want to work for you?

I'm lucky that I work in a place that values what I do, but I see too many of my documentation peers broken on a poorly-resourced wheel of disrespect. For those of you that don't feel valued?  Leave.  You and your skills are worth more than that.