Thursday 27 August 2015

Improving Documentation ROI: Part 6 - Production Line Efficiency

In Part 1 we looked at what ROI is, and how to calculate it.
In Part 2 we looked at the broad area of improving ROI by reducing costs.
In Part 3 we looked in a bit more detail at direct costs, and specifically direct financial costs.
In Part 4 we looked at reducing direct time costs for other areas of the business.
In Part 5 we looked at creating a passive time income to save you time in the future.

In Part 6, we're going to look at ways to save you and your writers some time by using production line efficiency.

I've mentioned previously that the production line ethos of increasing specialisation and efficiency is antithetical to an agile mindset.  However, in line with Agile's "inspect and adapt" mantra, there's no harm in taking the best bits of another system and adapting them if they benefit you. Efficiency is not a bad thing in and of itself, but it can be taken too far (my argument with Waterfall is that it worships efficiency to the point of stifling innovation).  With the caveat that you can have too much of a good thing, efficiency in your documentation process is something to be encouraged.

There is a whole corpus of knowledge about organisational analysis, so I'm not going to cover that kind of process here, but it goes without saying that someone needs to understand the documentation process in your team and company to understand where you can make efficiency gains.  This understanding can be gained incrementally over time, so as long as you understand some of the process you can start to find those gains.

At this point it must be stressed that "efficiency gains" do not cover things like cutting down on toilet breaks or doing time and motion studies to find the quickest path between 2 parts of the building at any given time of the day.  These things are for terrible bosses and people who are normally referred to by swearwords. Productivity is best served by an effective and efficient use of the people and tools at your disposal, and you can't divorce "efficient" from "effective".  Effective staff in an Agile environment are those with a degree of autonomy; it doesn't matter how efficient you make them if they can't be effective.  At some point you're joining the dark side of the production line by producing a command-and-control situation, which is precisely the opposite of an Agile environment.

But that's not to say that waste, in the Lean sense, can't be minimised.  Is there a quicker way to add the standard watermarks to your screenshots? Is there an information transfer process being used by one writer that gives them an edge on all the other writers? Does following a comprehensive check list make a complicated process quicker to complete? Are you doing things in an order that increases the chance of rework?  The list of possible waste in your processes is endless.

Once waste has been identified, and an effective and efficient process developed in place of the wasteful one, it needs to be documented in processes, procedures, policies and standards.  However, this is not necessarily for the reasons you think.  Yes, you need to mandate good practise if necessary, and it's always useful to write things down so you don't have to remember everything all the time (Hello! Documentation benefits 101!), but those aren't the most important time-saving reasons to have comprehensive, and where necessary proscriptive, processes, procedures, policies and standards.

The single biggest time sink is the decision making process.

Should I do it this way or that way?  What are the benefits of doing x instead of y?  What will the stakeholders say if I produce a document with/without ABC? Is it my job or their job to find this information out? Is this the right terminology? And so on, and so on, and so on, ad infinitum (or maybe ad nauseaum), release after release, writer after writer, year after year.  All that time, effort and energy taken up by working things out, second guessing other people's reactions, arguing with colleagues about why, what, when and who, agonising over synonyms, defending one position, attacking another, endless calories burnt in the pursuit of the "right" answer.  And then doing the same thing a year later when you've all forgotten why you made that decision a year ago.

That's waste.  That's serious, pointless waste. It affects everyone, it's completely unnecessary, and it can be prevented through the creation and continual maintenance of processes, procedures, policies and standards.  None of those documents will ever be finished or complete, because no-one can see every possible future, but they can be updated every time a decision is made about "how we do x", or "what we use for y" or "who is responsible for z", and over time they will get closer and closer to being comprehensive.  Decision making can be both difficult and time consuming for a lot of people.  Add in the fear of the cost of making the wrong decision in a work/career context and it can become paralysing.  And although Agile encourages group responsibility, the fact remains that a lot of people don't want the responsibility of making a decision.  Remember, the greatest efficiency of the production line is that the workers know what to do each and every time without making a decision.  We're trying to abstract that benefit away from the conveyor belt and use it to our advantage in a more innovative and autonomous situation.  This benefit is the lack of decision making that has to be done. So proceduralise things instead.  Make the decision once, then write it down, and use it as a guide the next time this situation comes up. If you make decisions based on minimising waste and delivering your responsibility to a high standard then the outcome of every question, every discussion, every debate, can be framed in your processes, procedures, policies and standards for the future.

Now the tricky bit: How do you calculate the ROI on this? 

In general you probably don't need to, because most companies aim to be CMMI/ISO/BS compliant (or whatever standards apply in your locale).  Documentation is no different to any other department in this respect, so you will probably have to have at least minimally compliant standards anyway.  But the kind of comprehensive processes, procedures, policies and standards I'm talking about go above and beyond compliance, and it wouldn't be much use telling you this will improve your ROI if I can't help you find a way to measure that ROI.

There's no getting away from the fact that you will struggle to find a definitive quantitative measurement of ROI in certain circumstances, and this is one of those circumstances. The notion of ROI does include intangible benefits, which are benefits to which a financial value cannot be assigned. Unfortunately for anyone trying to calculate the ROI of comprehensive processes, procedures, policies and standards, these are not intangible benefits, so difficult though it is, you have to do the work and calculate! Therefore, as discussed in
Part 1 of this series, we're going to use estimates and sensible assumptions, and as demonstrated in Part 4, we're going to calculate in units of time rather than money.

We need to estimate the cost of making the decision, and use sensible assumptions to work out the gain that comes from having that decision included in the standards.  For the sake of simplicity, we'll assume that:

1 - The word "standards" covers all processes, procedures, policies and standards documentation;
2 - Basic standards already exist and don't need to be created from scratch;
3 - Adding a decision to the standards (e.g. The process for creating X is A, B, and finally C) is a trivial task that doesn't have a functional ROI cost;
4 - The standards are proscriptive and will be used by all writers who are required to work to them.

The cost of making the decision will be the amount of time that it takes for the team of writers to:

 - Discuss the question;
 - Think of possible choices;
 - Debate those choices, and finally;
 - Make the decision. 


The question is "What should we call this type of field on a Windows form?" - 10 minutes
The choices are dropdown or picklist - 15 minutes
The debate is had, and includes a discussion of the agreed spelling, i.e. dropdown or drop down, and picklist or pick list - 30 minutes
The decision is made that this type of field will be referred to as a dropdown - 5 minutes

Total time taken - 1 hour.

The gain that comes from having that decision included in the standards will be the time it saves each writer on average in a specified time frame.  For the purposes of this we'll use 1 calendar year, but any gain will actually continue for the life of this standard.  The sensible assumptions we'll make are:

1 - Every writer will need to use the term dropdown;
2 - The term will be used moderately often;
3 - Until this decision was made, every writer used one or more of the terms discussed (dropdown or drop down or picklist or pick list);
4 - It took an average of 3 minutes to choose a term every time a writer had to make that decision (by checking with others, looking up previous documentation, etc);
5 - The choosing of a term was then remembered for a short period until it was forgotten, leading to 1 decision a month about this term per writer.

(You may feel that these assumptions are either not very sensible, or not very realistic, in which case you can use whatever assumptions you feel are sensible and realistic in your situation.  The important thing is to understand the logic of getting from the situation of making a decision to a calculation of the ROI.)

The gain is therefore 3 minutes per month, or 36 minutes per year per writer.

On the face of it, this seems like a negative ROI ((36-60)/60 = -40%), but remember that this is only for a single writer.  For 2 writers the ROI is 20%, for 3 writers it's 80%, and so on.  And a single writer would probably take a lot less that 1 hour to make this decision.  Finally, note that this ROI will continue year-on-year, so over 2 years for a single writer the ROI would be 20%, for 3 years 80%, etc. On top of this, there is the added benefit of increased consistency in the documentation, which means a more useful information experience for the reader, and a lower chance of help desk tickets being raised by users who struggle with inconsistent terminology.

This example is used because it is simple, and hopefully familiar to a lot of writers. It covers a standard rather than a process, because no two companies/divisions/departments are the same, and a process that makes sense for one reader will make no sense for another.  But the calculation of ROI will always take the same form - find the costs of discussing and deciding the process, find the gains that proceduralising it it will bring you, and do the maths.  It's worth remembering at this point that the goal of ROI calculation is to provide you with realistic, workable figures that can back up your proposal for more resources.  Aside from giving you more time to work on the things that can dramatically improve the documentation ROI (such as FAQ or Knowledge Base articles for the help desk's most asked questions), this kind of ROI calculation can help show that you've looked home first and made efficiency savings before asking for more resources.

There are a functionally limitless number of decisions to make about your documentation, and the more you proceduralise the more efficiency savings you'll make.  But as ever when you're flirting with the dark side, be careful that comprehensive standards don't tip into a command-and-control situation where the writers become robots, because you'll lose all of the benefits of being Agile, and gain very few of the benefits of a production line.  Documentation is not piece work!  But "efficiency" is not a dirty word, it's just a dangerous word.  Use it wisely.

In the next part of this series we'll look at personal efficiency, and how you can get more time in your day from doing the non-Technical Writing aspects of your job more efficiently.  Yup, that's right, we'll be tackling the beast that is personal productivity......

Wednesday 26 August 2015

Improving Documentation ROI: Part 5 - Saving Yourself Time

In Part 1 we looked at what ROI is, and how to calculate it.
In Part 2 we looked at the broad area of improving ROI by improving costs.
In Part 3 we looked in a bit more detail at direct costs, and specifically direct financial costs.
In Part 4 we looked at reducing direct time costs for other areas of the business.

In Part 5, we're going to look at ways to save you and your writers some time.  Specifically, we're going to talk about the following areas:

  • Passive income (templates, single sourcing, etc) 
  • Production line efficiency (procedures, standards, etc)
  • Personal efficiency (time/task/email management, saying no, etc)
So as not to confront you with a wall of text, I'll split this up into 3 articles, starting in this one with passive income.

One of the ways to increase your revenue is to have what is known as a passive income.  This is where you create something once and it makes money for you 24 hours a day without you having to do anything.  An example would be writing an e-book that people can buy from anywhere in the world 24 hours a day, 7 days a week, 365 days a year, without you having to do anything except file your tax return once a year.  The same principle can be applied to reducing time costs by the one-time creation of things that will save you time in the future.   Anywhere you have to perform a documentation task more than once is an opportunity to create something that will save you time in the future. Consider it a passive time income, if you will.  Examples for Technical Writers might include:

 - Templates - If you create the same type of document on a cycle (e.g. every sprint, every release, etc) then consider creating templates.  These will save you, and anyone else in your team who creates the same kind of document, time in every cycle.  There is also the added benefit of ongoing consistency and a single place to make changes for all future versions of the document.

 - Single sourcing - Some documentation, or parts of a document, can be used in multiple places (e.g. information in the release notes will also go in the help file, or instructions in the installation notes will also go in the configuration guide) or at multiple times (e.g. multiple minor release notes can be rolled up into a single major release notes document).  Single sourcing can be done by using help authoring tools like MadCap Flare to create individual pages that can be added to or subtracted from whatever target (i.e. document output) you specify. In these circumstances single sourcing will prevent you having to rewrite/copy the information, and all the attendant review processes that are implied by what is essentially the production of new documentation if you have to write it again.

 - Variables in your help authoring tool - All help authoring tools have the concept of variables (or something similar) which are used to place text in multiple places in your documents.  Changing the master variable will change it in every place in the topics you've used the variable in.  This is extremely useful for things like release numbers, company details, support desk contact information, etc.  Not only do variables prevent you having to do a search and replace across one or more documents, they also ensure consistency of text, so you know that as long as the variable is correct then that text will be correct everywhere that the variable is used. As an added bonus, you can usually set up a master project with variables and other elements in it, and import this data into new or existing projects so you don't have to set everything up each time.

These are a small sample of the possible ways you can reduce your time costs by using the "Create once, use many" principle, so inspect and adapt to fit your situation.  

The ROI for this kind of future time saving is as follows:

Cost = Time taken to create template/variable/whatever;
Gain = (Number of times the template/variable/whatever is used) x (Amount of time it would take to create the template/variable/whatever from scratch).


Time to produce a blank release notes document ready for the release cycle: 15 minutes.
Number of release cycles per product per year: 6
Number of products: 4
(i.e. 24 blank release notes documents are created each year)

Time to produce a blank release notes document template: 60 minutes
Time saved per template usage: 10 minutes (it still take 5 minutes to copy the template, add the release number, remove unwanted sections, etc)


Cost = 60 minutes
Gain = 24 x 10 = 240 minutes

ROI = (240 - 60)/60 = 3 = 300%

Bear in mind, as ever, that if your templates can be used each year with minimal or no tweaking you'll keep reaping the rewards year after year.

The simple maths indicates that you will save 3 hours a year, which might not seem like a massive amount.  But there is an economy of scale here, and the more documents you can create templates for, and the more writers who use them, the greater the saving.  There is also a hidden reward in that as long as the templates are right, your review process will be slightly shorter, and the number of errors that you need to fix will be lower.  (There are also the benefits of consistency for both the writer and the reader, but as this post is specifically about saving time I won't dwell on that).

Use the passive income technique to save your future self time in any situation where you could simply clone something, by creating the clone.  In part 6, we'll look at the time that can be saved by using some production line efficiency.

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:
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!