Thursday, 13 August 2015

Vanishing Standards?


The following comment was posted on LinkedIn recently by a fellow professional called Rupen:

"Recently, when looking for a Senior Technical Writer, I interviewed many, many participants with terrific CVs. I noticed that most did not follow basic writing principles; I try and adhere to the Chicago Manual of Style. They could write, but were unable to present information in a digestible manner. Each person seemed to have learned the principles once-upon-a-time, but after many projects, the principles vanished and delivery was more important. I wonder if this is because many companies have adopted Agile documentation practices.

I concluded that most people working as Technical Writers aren't really passionate about the field. They are makeshift technical writers, who'd rather be doing something else. It annoys me because the broader world of information experience deserves more respect.

...needed to vent!
"


Rupen's conclusion that "most people working as Technical Writers aren't really passionate about the field" strikes me as incorrect, but I understand his frustration, as did many other people on the thread.

I've also seen the problem that he faces, but the issue wasn't that the writers didn't care, it was that they either didn't know about style ("how to write") or their experience was that they didn't have time - nor any pressure - to write to a specific style.  Where Rupen is spot on is his assertion that "the broader world of information experience deserves more respect" (also, +1 for the previously unknown-to-me "information experience"
phrase).  This is the key to the problem, and it says to me that the candidates who don't know about styles are a symptom of a problem, not the problem itself.

I'll come back to that, but first a quick note about Agile documentation practises, because it's important that we don't conflate a move to Agile with a change in writing standards.  Agile does encourage "just enough" documentation, but that doesn't preclude high quality, consistent output.  It depends on what "just enough" means to the person responsible for setting the documentation standards, and also the documentation goals of the company employing the writer.  That is the same in real terms whether your company is Agile or not.

But back to the problem of which Rupen's candidates are a symptom.  I see 2 main issues which have caused a degradation of standards:

  1. An industry culture that assumes a documentation cost rather than a documentation value.
  2. An explosion in tech companies that need documentation.

Documentation Cost

Every writer has worked for companies that don't particularly value documentation, and in these companies the Technical Writing function doesn't get the resources, leadership, or, sadly, the respect that it deserves. This problem is very visible when it comes to things like standards, and the consistent application of those standards.  A move to Agile can be an excuse to do away with any gains that the Technical Writers may have made in this area, often by disseminating common misconceptions about the importance, or lack thereof, of documentation in the Agile process and using this as an excuse to end "expensive" things like peer-review and proscriptive standards.  Some of these misconceptions are dealt with here.  But a move to Agile doesn't mean that this WILL happen, just that it can happen.

I've said previously that this perception of cost rather than value is one of documentation's big strategic, structural problems, so I won't go over old ground too much.  But it speaks directly to Rupen's experience because a lot of companies don't want to put the resources into documentation, unless they're serious players like IBM or Microsoft.  


Part of this cultural problem - and it is cultural, because the benefits of documentation are legion and obvious to anyone with an ounce of common sense - lies in the fact that most tech companies are started up by developers, and most developers hate writing documentation.  That might seem like a trite observation, but how many tech companies have a developer right at the top?  A lot of them.  And by the time they sell to Google or Facebook or Microsoft or whoever, the culture is set and the technical debt in documentation is almost too large to be sensibly paid.  Which brings me neatly on to point 2.

Lots More Tech Companies

Since Sir Tim Berners-Lee invented the World Wide Web in late 1989, there has been a profound change in the pace of company growth.  Companies like Uber, Square and Pinterest, with virtually no staff or bricks-and-mortar resources, have achieved in a few years a market capitalisation that took traditional companies decades to reach. The WWW and the underlying infrastructure of the internet have brought about the biggest single democratization of wealth creation through creative ideas in the history of mankind.  Isn't that awesome?  Can I get a high five?  Yeah, high five.

Now, not that I want to burst that bubble, or make it all about documentation, but democratisation does have some drawbacks.  One of those is the lack of command-and-control.  Dijkstra would be turning in his grave if he knew about all of the code out there that he would consider harmful.  If we had command-and-control, or at least trained dinosaurs:



https://sslimgs.xkcd.com/comics/goto.png
High Five?


Then this could be controlled.  But the WWW is a democracy (or Wild West, depending on your preference), so it can't be controlled.  The explosion of tech companies has meant that there just aren't enough writers with experience of documentation good practise, like proscriptive standards, principles of consistency, a lack of dialects, and so on, and those that have it often coagulate in bigger companies that have been around for a while.  This is because those companies are prepared to pay time and money for high-quality documentation, and writers who've worked in that kind of environment are often loath to leave for the chaos of a much younger company where they will spend most of their time explaining why documentation is important.

I've interviewed many people who have experience of working with tech companies I've never heard of, and when you look up those companies, a lot of them are 10 years old or younger.  As documentation is often one of the last things to be properly implemented, is it any wonder that these people haven't used, or maybe ever seen, decent standards, processes and procedures?



In summation then, lots of tech companies, created by people for whom documentation is an afterthought, combined with not enough experienced writers, means a lack of credible candidates.

Whatever the cause of this problem, I'll say one thing:  Everyone I know who writes for a living does it because they are passionate about it. It's up to those of us with some experience to teach them what they need to know to turn their passion into good documentation. Bang the drum, people!