How to Scale Documentation, Part 3

I'm glad you're starting with Input processes, it's always better to start with the meat of the subject.

You're a writer, aren't you?

  
Yes.  Well, Information Engineer, technically, but writer will do.  How did you know? 

The people that write and maintain the documentation (i.e. provide the Input) always think that the Input is not only the most important part, but also logically the first stage. 


Creation and maintenance of the documentation IS the first stage, surely?

Not normally.  In Part 1 we talked about the Input > Delivery > Feedback cycle, if you remember. When you create documentation for the first time you might think that Input is the starting point of that cycle, but in actual fact there is no starting point.  The Input will come from the Feedback, be that a customer request for documentation, a legislative need, a stakeholder requirement from a user story, or something else.  The Feedback in turn comes from Delivery, which came from the previous Input, and so on. 


Ah, so Input isn't as important?

Not at all, I'm just illustrating a point: All 3 parts of the cycle have equal value.  As mentioned at the start of this series, you can't scale past a bottle neck.  If you have a bottleneck in any one of those 3 stages then you can't properly scale your documentation.  Besides, if you don't create and maintain your documentation there'll be no Delivery and the Feedback will be all negative, so let's not denigrate the Input.  It's absolutely critical.


Glad to hear it.  Let's cut to the chase: how do you scale the Input?

As mentioned in Part 2, scalability is the ability of your processes to handle a lot more work and still run at the same level of efficiency.  This means that you need to remove the following things from your processes where possible:

1. Unnecessary/complicated process steps;
2. Bottlenecks;
3. Anything done by humans which is better done by a machine;
4. Decision making.

You need to replace all of those things with efficient and effective tools, processes, procedures and standards.


Remove decision making?  I'm not a robot, thank you very much!

No you're not, but there are some decisions you don't need to make, especially not again and again.  I'll come back to that though, don't worry.


Hmm.  Carry on then....

Much obliged. The reason you need to remove these things is that the more steps in a process, and the more complicated those steps, the more difficult it is to scale that process.  

• Every step has a resource cost, so the more steps there are, the more resources that process burns up.  The more resources a single process needs, the more difficult it is to scale it without the cost becoming too high.
• The more complicated a step (or series of steps), the higher the cost of performing that step because a) specialist skills or knowledge are required which means expensive people, and b) "complicated" almost always means "time-consuming and prone to error".

Therefore you get rid of every unnecessary step, remove bottlenecks that channel everything through one individual or tool, stop making the same decisions over and over, and automate whatever you can.  We'll look at some specific examples of each of these next.


Hang on, are these Input-specific, or do they count for all 3 stages of the cycle?

They count for all 3 stages of the cycle to a greater or lesser extent.  However, decision making is much more critical in the Input phase than anywhere else in the cycle, because the Input phase is the most creative part and as such there are many more decisions to be made.  Decision making scales terribly! We'll be looking at Delivery and Feedback mechanisms later in the series but as a sneak peek, once those mechanisms have been decided you'll spend more time on automation (for Delivery) and removing unnecessary process steps (for Feedback) than removing decision making.


Shall we start with unnecessary/complicated process steps then?

Yes.  Process steps for the Input phase - that is, creation and maintenance of documentation - start at the point where a story is added to the backlog ready to be groomed.  However, at this point you'll still be working within your scrum team process to groom and estimate the backlog items rather than within your documentation process.  Agile processes scale well already, so we'll start on Day 1 of your sprint when you're working under your documentation processes and standards.

An example of an unnecessary process step would be having to create your skeleton documentation from scratch every time.  Aside from the fact that this provides an opportunity to make a mistake and/or make your documentation inconsistent, it takes time that could be better used actually writing content.


Templates, then?

Absolutely.  I've talked about this before so I won't rewrite it all again but I'll quote this one sentence:

"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."

Apart from the ROI benefits, using templates, single sourcing, variables and so on will remove unnecessary steps from your process and thus make it more scalable.

As far as complicated processes go, the definition of "complicated" is very contextual.  The fact that something is complicated to me doesn't mean it's complicated to you, so I'm hesitant to give a concrete example.  As a general principle, if you can't fairly easily teach a colleague to follow that process correctly, then it's too complicated to scale well.  Break it down into smaller steps or find a less complicated way of doing it (see automation, below).


Interesting. Ok, what about bottlenecks?

A bottleneck is any step in the process where only one document can go through that step at a time at the normal speed.  This generally takes the form of a lack of resources in one of the following areas:

• People - an example would be a process step that only one person can perform because of skills, authority, permissions, etc;
• Tools - an example would be a process step that requires a tool for which you only have one license;
• Bandwidth/processing power - an example would be a build server that builds your help output but only has enough processing power to build one help output at a time without degradation of performance. Or having a network without sufficient bandwidth to upload/download multiple help outputs concurrently.

There are a myriad possible bottlenecks; the key to finding them is to run your whole process end-to-end for several documents concurrently.  If at any process step you develop a queue, or could have developed a queue in any easily-obtainable circumstances, you've got a bottleneck.

Remove bottlenecks by providing what you need - trained/authorised people, tools, bandwidth/processing power - or by removing/amending that process step.


Which presumably brings us on to automation, right?

Right.  Well figured out, by the way.  Yes, automation can be a very useful tool for preventing bottlenecks, although there are plenty of other benefits to automation. Computers are very good at rule-based calculations, whereas humans aren't.  This makes computers particularly useful for performing steps that involve checking things - like a spellchecker - or steps that involve changing or selecting many things based on a rule.

A simple example would be using variables in your help authoring tool for pieces of text that occur in many places.  If the text changes, you change the variable and it gets changed everywhere in your documentation.  Similarly, you can use tags to choose what documentation will be included in a compilation (this is part of single sourcing).

A more complicated example would be writing a batch script that compiles a documentation project, or using VBA to write formatting macros in a Word document.  Automation can be as complicated as you want it to be, and it's up to you to determine what the ROI on the initial investment in automation needs to be to make it worthwhile.  But computers and the programs they run typically scale a lot more easily than people and their skills, so if you can automate a step in your process, even partially, do it.  


Sounds like that requires a decision.  Didn't you say to remove decision making?

Yes, although I said "where possible" and I was referring to decision making within individual process steps.  You still need to - and should! - make decisions about those process steps.


Why would I want to stop making decisions within the process?  Writing is a creative skill, and that means decisions.....

You're partially right, because writing is partially a creative process.  But it's also a proscribed process, at least when you're writing technical documentation.  It's those proscribed bits, like writing standards and responsibilities, that you shouldn't be making decisions about.

The lack of decision making is the biggest efficiency saving that you get from a production line and this can be used in the documentation process to allow the writer to concentrate on the creative part of their job.  I've covered this in a fair amount of detail before, and I'd encourage you to read that post to fully understand this.  One of the key takeaways is that:

"The single biggest time sink is the decision making process."

Your Input phase will not scale if each individual writer is making decisions about writing standards, terminology, responsibilities, and so on.  These things needs to be documented outside of the day-to-day documentation process and applied to the Input phase for all documentation.


So we should have proscriptive and general standards to allow us to focus on the specifics of what we're trying to write?

Exactly.  Writing is a hard-won and specialist skill set and writers should be given as much time to write as possible. Any process step that requires a writer to make a decision that in theory should apply to all documentation - e.g. the correct terminology to use - is a process step that can't be scaled because decision making can't be reliably replicated at the same level of efficiency.  And it's a waste of time for writers to keep having to make these decisions again and again, as well as leading to inconsistent and therefore poor quality documentation. 


I've read that article you linked to, makes a lot of sense. 

Stop it, you're making me blush.


Uh-huh.  Moving on, is there anything else I can do to scale my Input?

As long as you remember the principle that you can't scale past a bottleneck, and cover the 4 points I mentioned above, you should be able to run your Input phase with the same efficiency no matter how many documents are being worked on concurrently.


Excellent.  See you next time to talk about Delivery?

I'm already looking forward to it.