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.

 

How to Scale Documentation, Part 2

Right then, let's get on with this.  How do I scale my documentation?

Did you think about where your processes fit in the Input > Delivery > Feedback cycle, and what bottlenecks you've got, like I asked you to in Part 1?


Yes, although I thought bottlenecks affected efficiency more than scalability...

They can do, but not necessarily. Efficiency and scalability are closely related.  Would you like me to clarify the difference for you?


Um....

It's OK, lots of people are confused by this.


Really?  Alright then, what's the difference between efficiency and scalability?

Efficiency is a measure of what you can get done, with minimum waste, given certain requirements.  The requirements normally relate to the end product, so in the case of documentation the requirements might be the accuracy, consistency and completeness.  If you've reached a situation where there is no way to go through the Input > Delivery > Feedback loop cheaper (in resource terms) or quicker without breaching the requirements then your processes are 100% efficient.


So efficiency is relative to requirements?

If you're talking about the mathematical definition of efficiency, no. Efficiency is essentially the ratio of output to input, and this can be measured very precisely (Warning: Link takes you to a PDF.  Of maths.).

In the practical terms we're interested in though, yes, efficiency is relative because, for example, some waste in your documentation processes might be an acceptable trade-off for significantly increased speed.  It depends on what requirements you measure the efficiency against.


Right, I see.  Carry on then.

A process is generally linear.  This means that you perform one step at a time, one after the other, until you've completed all of the steps in the process.  Although the order of the steps may not matter, and you might be able to start some steps before you've completed the previous step, the general concept of a process is that it is a sequence of steps to achieve a goal.

Efficiency can be thought of as minimising both the number of steps and the time it takes to complete each step whilst still meeting the requirements.  The elimination of the un-required steps and speeding up of the required steps is the removal of waste from the process.  (This concept should be familiar if you've ever seen the Lean process at work.)  


Gotcha.  What's scalability then?

Scalability - in this context - is the ability of your processes to handle a lot more work and still run at the same level of efficiency.  In other words, it doesn't matter whether you have 1 document for 1 release or 100 documents spread over 10 releases, your processes should still work just as efficiently.  

Included in this is the ability for multiple resources to work through those processes concurrently.  This is why bottlenecks need to be addressed. If only 1 person can perform part of the process then whilst your process might be very efficient for 1 document for 1 release, it isn't a scalable process because only 1 document can go through that process at any one time.  That means your process doesn't allow multiple resources to work concurrently.  


Ahhh, so bottlenecks might only become apparent when you try to scale, right?

Spot on, gold star for you! Removing un-required steps and speeding up slow steps will make your linear process more efficient, but not necessarily help you with scaling if your process has a bottleneck that only affects concurrent resources.


I see, I see. I might need to go back and look at my processes again....

Take your time, I'll be here.  When you're ready, we'll start going through the Input processes of your documentation cycle in part 3 and make some suggestions for making sure it can scale.

How to Scale Documentation

Firstly, what does "scale" mean?

Scaling applies to systems and processes.  It is most frequently associated with computer hardware systems, networks and algorithms, although it applies to anything which can grow to accomodate more work.  As an example, a network is said to be scalable if it can handle an increased number of nodes and increased traffic without requiring anything more than perhaps some additional hardware to be bolted on. 

"In practice, if there are a large number of things (n) that affect scaling, then resource requirements (for example, algorithmic time-complexity) must grow less than n² as n increases."  


Interesting.  Can you scale documentation?

Yes.  The processes that you use to generate and deliver your documentation can either be scaled - i.e. you can take on the production and delivery of more documentation with no loss of speed and quality - or they can't.  Where a computing process may need more disc space or processor power in order to scale, your documentation process might need more writers in order to scale.  That's fine, a process that can handle more work if you add more people is scalable.  A process that can't handle more work by adding people is not scalable.  (There are other things like bandwidth you might need more of to scale your documentation and we'll talk about that a bit later on.)


Great, ok, like it.  What processes need to scale?

There are 3 documentation processes that need to be scaled:

• Input (creation and maintenance)
• Delivery (released to customers)
• Feedback (bugs, change requests, stakeholder enhancements)

This can be visualised as:
 

That's it? Just those 3 processes?

Yup.  Those 3 processes cover the whole documentation lifecycle.  Everything that happens to documentation comes under one of those 3 processes.  The end of life of a piece of documentation - e.g. when a product is discontinued - is covered by Delivery: you deliver the last iteration of the documentation, place the documentation into the standard repository and then start work on something else.  In this specific case the cycle ends there as there will be no feedback.


Fair enough, sounds good.  Any high-level principles or rules of thumb to follow?

Only one:
 
                         You can't scale past a bottle neck.

This means that if there is a bottle neck in one of the 3 processes, your documentation won't scale. Even if the Input and Delivery both scale with perfect efficiency, and 99% of the Feedback scales perfectly, if that 1% causes a bottleneck then your processes don't scale.  It's all or nothing.  That doesn't mean you have to have an entire system set up to be 100% scalable from the start (that's unrealistic) but until all 3 processes scale completely, you haven't scaled your documentation.  Nature abhors a vacuum, scalability abhors a bottleneck.  Both will get filled extremely quickly.


Are you quoting an Ancient Greek philosopher just to look clever?

Partly.  But there's a serious point to be made about bottlenecks, which is that they will fill up very quickly as you start to scale and thus prevent you delivering more documentation, even if you have more resources.  I'll say it again: You can't scale past a bottle neck.


Right, bottlenecks are bad, I understand, stop banging on about it..... 

As long as you're sure you get it. It's critical.


Critical, roger that.  Let's move on.  How do you make your processes scale?

We'll start looking at that in the next part.  For now, have a think about your own processes and try to identify where they sit in the Input > Delivery > Feedback cycle, and what bottlenecks you've got in those processes.  That'll help you apply what we're going to talk about to your own situation.


You're giving me homework?

I am.  Get on with it, I'll see you in part 2.

*sigh*

What is the Optimal Writer:Developer Ratio?

This is a tough question to answer.  How do you make that assessment?  What is the industry standard?  What metrics should you track to get empirical evidence?

These questions are particularly apposite if you are requesting more documentation resources, because the person you're asking will - quite legitimately and fairly - want some form of business case involving figures and evidence.  But if you've searched for answers to these questions you probably haven't found a lot of concrete information.  I've had discussions about the optimal writer:developer ratio lots of times, with lots of people, in both serious budget discussions and informal chats, and with staff at every level from newbie to director.  This isn't a topic that never gets mentioned, or an obscure branch of technical writing that only a tiny number of people ever wonder about.  It's a question that most Tech Writing/Documentation Managers has either asked or been asked at various times in their careers.  It's a live question for a lot of us, today, in the jobs we're in.

But this question seems to be under-represented when it comes to answers, or at least  methodologies for finding an answer.  Interestingly I found a lot more information when looking for the tester:developer ratio.  At least there were a lot more articles discussing the topic.  I'd guess there are more blogs by technical writers than by testers, simply because writers tend to like writing, and yet here we are.  Perhaps this is something to do with the difficulty of quantifying documentation? It seems like this is one of those questions that has people going round in circles and so they just stop thinking about it and accept whatever ratio they're given before they go mad.

When I sat down to write about whether documentation should be in the definition of done, I found a similar situation.  There was a lot more discussion of the topic, but no-one had a real answer, or a good way of getting there.  Generally everyone pounded on each other's ideas because "my scenario is different so that won't work for me" and "there is no answer, it's all contextual, here's a context where your idea won't work".  This continued until people got bored and stopped posting on that thread.  So I went down the road of "what are the questions you need to have answers to before you can decide if documentation should be in the DoD", and that approach seemed quite useful to some people.

Let's follow a similar approach here and ask: What information do you need to know before you can decide how many writers you need? Note that there is a re-framing of the question here, from a question about a ratio to a question about a number.  This is because I work in agile environments and that changes the nature of production from one where you have X developers, Y testers and Z writers in a large pool to one where you have small teams that each have x developers, y testers and z writers.  Therefore it doesn't necessarily make sense to focus specifically on the writer:developer ratio, but it does make sense to focus on the number of writers needed in each agile team, and then use this to get a total number. Also, when you talk of an "optimal ratio of writers to developers", what defines optimal?  You have to have something against which to judge "optimal", and these questions should help you figure that out.

Before we go on:

 - Because it's more of a general resource planning and managerial standard, I'm assuming you've already taken into account the need for cross-training and knowledge transfer to prevent single points of failure, the expectation that you need holiday or illness cover, and generally are aware of the need for slack/contingency in the system.

 - Regular readers will know that I consider multi-functional teams to be a unicorn - very desirable and very rare to the point of being largely mythical - because it is very difficult to be professionally competent at even 2 of the roles you need to produce good software, let alone more than 2.  Therefore I have no truck with commentators who suggest that there "is no separation between content developer and software developer".  Not to gild the lily of my previous arguments on this point, but if your developers are Richard Stallman, Linus Torvalds and Vint Cerf then a) why the hell are they spending their time producing end-user documentation, and b) any professional writer will be able to write better documentation than any of them.  Let's not pretend that a multi-functional team of very technical non-writers will produce good documentation. They won't.  

Right, the questions:

1. Are your writers part of the scrum team?
2. How are you handling peer review?
3. How much documentation do you need? 
4. What kinds of documentation are needed?
5. Who is responsible for bringing together the finished documentation set?
6. How good is your design team? 
7. How much technical debt does your product have?
8. What SHOULD your writers be doing, vs what ARE they doing?

1 - Are your writers part of the scrum team?

If they are, they shouldn't commit to a sprint if they can't document it. If the writer or writers in the team are a bottleneck that cause the other team members to commit to less than they can do (because the team can only go as fast as it's slowest member), then you need another writer on that team.  This does make the assumption that it is sensible for documentation to be in the definition of done, so make sure that the problem is a lack of resources rather than a situation where there's too much documentation to be done in the last couple of days of the sprint.  If your writer has very little to do in the first half of the sprint, that's not a resource problem, that's an organisational problem.

If your writers aren't part of the scrum team - e.g. they work a sprint in arrears - they should still be committing to the sprint when the team does, even if they won't document it until the next sprint.

2 - How are you handling peer review?

Do the writers have to build in time for peer reviewing each other's work into their willingness to commit to a sprint? If so, do developers and testers have to do similarly for the work of their peers?  If it's only the writers who have to do this, there is an additional overhead that will cause them to be able to do less writing, which means it is more likely they'll become a bottleneck for the rest of the team.

3 - How much documentation do you need?  

This isn't about types of documentation, which is covered in the next point, but simply about the volume. For Clash of Clans the documentation required is minimal, no matter how many developers you have.  But for Microsoft Excel the documentation required is huge.  1000 developers working on a black box that takes in one value and spits out another might only need 1 writer.  10 developers writing a complex, parameter-heavy application with multiple APIs, web services and SDK hooks might need several writers. (This is the main reason why there is no point suggesting a generic writer:developer ratio.)

4 - What kinds of documentation are needed?

Unlike the volume question, this is about different types of technical documentation. If you have multiple specialist documentation needs, e.g. API, SDK, end user, configuration, specification, FAQs, raw HTML/CSS web pages, sales engineering, technical marketing, etc, then you'll need more than one writer, even if some writers are not team-specific (e.g. the SDK writer may work outside of the scrum teams).  Ultimately, you need to document all of the tasks that a user could perform, and you need those tasks documented by people who understand what information different users will need (e.g. a data entry end user needs to know very different things to a developer end user who want to use your API).

5 - Who is responsible for bringing together the finished documentation set?

This is for situations where multiple teams feed into the same product (or product set). Do your writers just write, or do they design documentation, mock-up screenshots or wire frames, deal with translators or printers, manage other writers, and so on?  If any or all of the writers have responsibilities that go over and above writing documentation then you should consider hiring an editor, principal writer, documentation manager, translation manager, or other specialists who can manage these complex issues with a view over all the documentation and products.  As a side note, this should have a decent ROI because a specialist will be more efficient and more capable of achieving economies of scale across all documentation sets.  They'll also free up the writers to do what they do best: writing.

6 - How good is your product design? 

Good design should eliminate a lot of the need for writers, because the design makes the software intuitive to use. For those of you that have used both products, think of the difference between the TFS and JIRA work item tracking applications.  TFS has been designed from the ground up to be easy to use and to be fully integrated into the .NET framework and IDE, as well as being "Agile-native". This makes it intuitive to use, and as such the documentation can primarily focus on SDK and API integration, rather than end-user documentation.  JIRA has grown organically from a defect tracking system and has had various elements bolted on in response to market needs.  This makes it difficult to use, and the end-user documentation is accordingly much greater.  I'm not suggesting that all Microsoft products are this intuitive (SharePoint being a great example of something that's really not), nor suggesting that all Atlassian products are difficult to use (Confluence is the most user-friendly collaboration tool around), just that TFS and JIRA demonstrate how 2 different applications that do roughly the same thing can be miles apart in usability and therefore documentation requirements.

7 - How much technical debt does your product have?

I've said before that documentation shouldn't be used to cover technical debt, but let's be honest: it often is.  If your product has a lot of technical debt this will make the documentation that much more complicated and voluminous, which will mean that you may need additional writing resources to compensate.

8 -  What SHOULD your writers be doing, vs what ARE they doing?

Start with a list of the thing your writers currently do, then write a "dream list" of everything you think they should be doing instead of/as well as what they're doing now.  Write down everything you can think of.  Then scrunch that list up and throw it away because it's madly unrealistic (but it's good to get it out of your system), and write another list of what could be achieved if you had additional writers.  Focus on improving efficiency and customer satisfaction, and decreasing support costs. This is ROI 101 and you want to focus on selling the idea of increasing sales and decreasing support costs.  There's no point trying to sell an "optimal writer:developer ratio" because a) that's not going to get anyone motivated to support you, and b) there is no such thing as an optimal writer:developer ratio, which is one of the reasons you're reading this. 


When you've got answers to all of these questions you should have a better idea of, and better evidence for, the number of writers you need in each scrum team.  Add those numbers up, and that's your overall answer.   

An Alternative to a Hierarchy

When building documentation management systems (DMS) there is a temptation to put all of the content into a hierarchy of one kind or another.  This isn't always a mistake, but it shouldn't be the default structure.  In fact, I'd go so far as to suggest that it should only be used when there are compelling reasons to do so (and "I'm the most important person and I want a hierarchy" is not compelling).

A note for those who might not have a DMS in place yet, or those who want to learn more about them: A DMS is more properly called an EDMS, or Electronic Documentation Management System, but the "E" is often left off due to the assumption that people are talking about the management of documents on computer systems.  A non-electronic DMS would nowadays probably be akin to archival work.  DMS is not carried out using a normal file system like Windows Explorer (at least, not by professionals), but rather on specialised software tools that have functionality like version control, check in/check out and permissions.  Examples would be Documentum and SharePoint, but there are many others.
 
So, if not a hierarchy then the obvious question becomes: What structure should be used instead?

The obvious answer is: A tagged heap.

By a tagged heap, I mean a heap, a pile, a bucket, a single folder/list/library that contains all of your documents, with each document tagged, labelled, indexed, categorised or having otherwise had metadata applied.  Retrieval becomes a matter of searching, filtering and ordering rather than navigating, drilling down and visually scanning.  In most cases it's quicker for users and easier for administrators to maintain in the long term.

This is a big claim, especially if you've never been exposed to the power of searching a tagged heap. Also, hierarchies are popular, and the power of control they offer is a hard thing to give up, so I might have some convincing to do.  Let's start that by looking at the pros and cons of hierarchies:

Pros of folder hierarchy

• Already understood and used by computer users - low to none learning curve for functionality;
• Easy to permission a folder (and by extension all of the files inside it);
• Low cost of setup;
• High level of control for administrators.

Cons of folder hierarchy:

• Content can only be stored in one folder (and by extension one place in the hierarchy);
• High learning curve for large or complex hierarchies;
• Only someone who knows the whole hierarchy can move through it efficiently or quickly;
• High cost of moving content in the event of a change of hierarchy (e.g. due to organisational change);
• "Logical" for the hierarchy creator will not be the same as "logical" for a lot of the users;
• Very inflexible;
• No standardised metadata between different file types (or versions, such as .doc and .docx);
• Searching is difficult if you don't already know the name and location, leading to user frustration.
• Slow to click through folders, read the next list of folders, click the next folder, etc, etc.

What can we take from this? Well, folder hierarchies might be familiar and easy to use, but they're inefficient, inflexible and illogical for a lot of users.  Familiarity and ease of use are all well and good, but there is a significant life-long cost to that which is hard to justify. The two costs that stick out immediately are the high cost of administration AND the high cost of using.  Isn't that actually a worse case scenario?  That's only 1 step above not having a DMS at all.

Still, familiarity breeds both comfort and contempt, and maybe I've gone too far towards the latter.  After all, there's a reason folder hierarchies are so popular and ubiquitous, and it can't be because people actively like things that are rubbish (no X Factor jokes, thank you very much).  So people must value the control a hierarchy gives them and the low cost of setting up and permissioning folders, because those are the big benefits, right? Or, is it because there is no obvious alternative? Or that people can't see the benefits of an alternative?

A tagged heap is a strong alternative, and has a lot of benefits.  Let's look at the pros and cons.

Pros of tagged heaps

• Content can be viewed based on any number of searches, orders and filters, so location doesn't matter;
• No learning curve as search is as ubiquitous as folders;
• A system novice can find something as quickly as a system expert;
• No cost of hierarchy change;
• No logic gap between creator and user;
• Infinitely flexible, as views can be created in any way the system allows;
• Standardised metadata across all file types (using things like mandatory columns, labels, etc);
• Searching is easy because of the metadata (such as date of creation, author, file type, description, etc)
• Extremely fast file retrieval (modern search algorithms can search and return results from tens of thousands of records in less time than it takes to blink your eye).

Cons of tagged heaps:

• Higher learning curve for users who are adding documents, especially for adding metadata;
• Permissions can require more design;
• Higher initial setup cost;

Unlike a folder hierarchy, the more a user puts in the more they get out. This specifically applies to metadata, but on the basis that, as every administrator of every system ever built knows, not every user is as diligent as they should be, any modern DMS system can be setup to make metadata entry mandatory.  The more metadata is entered, the more powerful the views and searches will become.  This does require an intelligent, thoughtful approach to metadata design though, hence the higher initial cost of a tagged heap system.

My argument would be that ease of setup and ongoing administration is not as important as ease of use for the people who'll be using the system on a daily basis.  A balance does need to be struck, because a system that's incredible for the 50 people who use it, but for which 50 administrators are needed, isn't a sensible purchase, but in general the users of the system are the ones who'll determine its success (or not).  We've all worked in places where a decision has been made to implement a system that the directors and/or administrators love, but which is execrable for the users.  And what happens? People use it as little as they can get away with, thus removing a lot of the intended benefit.  There's no point implementing a system that has such a poor ROI.


Although using a tagged heap does have a higher initial cost, the benefits for the users are legion and compelling.  On that basis, I'd use a tagged heap and consign complicated hierarchies to the recycle bin by default.

If you've got experiences that confirm or contradict the benefits and ROI of a tagged heap, drop a comment in below and let everyone know which you prefer.

Improving Documentation ROI: Part 7 - Personal Productivity

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 looked at creating a passive time income to save you time in the future.
In Part 6 we looked at ways to save time by using production line efficiency.

In part 7, we're going to look at ways to save time by improving your personal productivity.


As has been mentioned on many occasions in this series, time = money.  When it comes to you, it's your time, which means that everything you do costs the company money, because they're paying for it.  More than that, if you want to be a effective employee (or director, or company owner, or contractor, or hobbyist) you will need to have at least some basically efficient personal routines and habits to prevent you spending time on things which you either shouldn't or don't have to do.  This is where the concept of personal productivity is useful.

Personal productivity means different things to different people but for our purposes, where we're looking at improving documentation ROI, it means using your time efficiently and effectively to maximise your writing time.  The more time in the working day you can dedicate to researching, learning, writing, reviewing, proof reading, and all the other things that us writers have to do, the more documentation you can produce, and the higher the quality of that documentation.  

With that in mind, there are 2 main areas that are worth investigating to see if you can save yourself time or make better use of non-writing time:

1. Time Management - This has 2 core components: you, and other people.  Managing your time well means cutting out interruptions, distractions, intrusive communication media and task switching as much as possible.  All of these problems are caused either by you (especially distractions and task switching) or other people (especially interruptions and intrusive communication media).  The goal of a time management system is to spend your time working on the most important priorities, not whatever is deemed most urgent by the other people interrupting you, and to spend that time in blocks large enough to allow you to focus properly. 
2. Task Management - This is the art of capturing, processing, doing and reviewing tasks, whilst using planning and prioritising to make sure you do the right tasks, at the right time, in the right order.  Task management covers both repeating tasks (either regularly or irregularly) and one-off tasks.  The difference between the repeating and one-off tasks is that whilst you can build an effective methodology for getting from start to finish that works for both types, you generally only have defined routines and habits for repeating tasks.  This is for the obvious reason that by definition there can't be defined routines and habits for one-off tasks.

A lot of personal productivity training will focus on getting the right things done without wasting time on unimportant or unproductive tasks.  The definition of "the right things" will be different for different people, roles and situations.  For a personal assistant, emails, phone calls and calendar organisation are the right thing to focus on.  For a professional technical writer those things will be the wrong thing to focus on, at least most of the time.  Ultimately, the decision on what are the important and productive tasks is entirely contextual, but I'm going to assume that the right thing for you to focus on is producing high-quality documentation (including the non-writing tasks such as information gathering that technical writing requires).

To that end, the specific skills to develop are:

• Communications management (emails, phone calls, IM, social media);
• Capturing and processing tasks into a system;
• Assertiveness;
• Effective communication;
• Saying No to people;
• Managing expectations;
• Prioritisation;
• Planning.

And the general skills to develop are:

• Understanding the power of building and maintaining routines and habits;
• Why building a system is useless unless it works and you use it;
• What motivates you to get things done;
• What motivates others to help you (or leave you alone); 
• How to achieve a state of flow;
• How to not panic or have a breakdown.

Depending on your current level of productivity and your work situation there will be other skills you need to develop, but these cover the majority of things which take away time and focus from the important work, and also the basics of getting that important work done. But bear in mind that getting a productivity system in place and working is like giving up smoking - you can use all the patches, sprays, and other aids you want, but ultimately willpower is required. Don't fall into the trap of thinking that the system is the important part, because it's not.  You're the important part.  The systems you develop to make yourself more productive are only useful if a) you use them, and b) they actually make you more productive.  One of the easiest mistakes to make is to spend more time finessing the system than actually using it.  This is particularly easy when you're something of a perfectionist or you have a tendency to get deep into the detail rather than the big picture.  Keep the ultimate goal of increased productivity in mind.  Tweaking your system to the nth degree is not productive.


If you've noticed that nowhere in those bullets points does it mention anything to do with writing skills, help authoring tools, or anything else that is specifically related to producing documentation,  then congratulations and have a gold star on me.  It's a fair question to ask: How can I talk about personal productivity as a writer without mentioning writing?  

The equally fair answer is: Because I'm not talking about how to write productively (or well, or better, or more efficiently), I'm talking about how to consistently create and maintain the conditions you need to write.  What, why, how and when you write is up to you, although of course I'm not averse to throwing my two penn'orth into that discussion.  But that's for another time.  This is about getting you set to write and that's enough for now.

Getting back to the point of this article: Calculating the ROI of personal productivity can be tricky, but it requires the same calculation as any other project: Work out the time it takes to build the systems you need, work out how much time they'll save you over a defined period, and plug the numbers into the equation.  However, in this instance it might not be worth performing this exercise unless you need to justify what you're doing, because the return will be difficult to predict and you are unlikely to need budget approval for an activity that shouldn't require much if any outlay other than your own time.  And, if you're serious about being more productive, a lot of the thought that needs to go into the system can be done on your own time. 


I'll be covering all of these skills in a future series, but not as part of the series on ROI.  If you want to crack on with improving your personal productivity, there is a slew of personal productivity information on the web.  When I made that search, there were over 35.3 million results returned, so there's plenty of resources to help you.  Good luck, and like all things in an agile world, don't be afraid to inspect and adapt to make the systems work for your personal system.

A more normal service will be resumed in part 8 of this series, where we'll switch from looking at saving costs to actually generating revenue.

The Basics - What is Single Sourcing?

A concept that comes up regularly when discussing best practise in technical writing is single sourcing.  What is single sourcing, and why is it often considered to be best practise?

Single sourcing can refer to any one of the following:

• Creating one document and producing it in different formats (e.g PDF, CHM, HTML, etc);
• Creating one document and using it as the basis for different documents (e.g. Installation Guide, Configuration Guide, Administration Guide);
• Creating a topic or piece of content (often called a "chunk") and using it in multiple documents and/or in multiple places in the same document.

Single sourcing is an example of the "Create once, use many" philosophy. It is also known as content reuse and is analogous in concept to code reuse, in that you can change the source code/documentation, compile your project and create a new deliverable with that change made everywhere the content is reused.

Markup languages like HTML and XML allow the divorce of content and presentation. The essence of single sourcing is to write the content once and then use markup to present it in different ways.  This can be in a different format - PDF, CHM, HTML, printed, etc - or in the same format but with different content "chunks". Large, homogeneous documents such as entire help files don't lend themselves to single sourcing, unless identical copies are going to be created in different formats (e.g. a PDF and a printed format).  Therefore single sourcing requires a topic based authoring approach, where individual topics can be reused in different outputs and in different formats.  It is for this purpose that DITA and its structured topic approach were designed.

 

What are the Benefits of Single Sourcing?

The primary benefits of single sourcing are that it:

• Has a single content source to maintain;
• Prevents out-of-synch problems;
• Reduces rewriting of the same information;
• Reduces review and editing load;
• Increases consistency of documentation.

Structured, reusable content also provides an element of future-proofing against new distribution channels such as mobile or social media.  A new presentation wrapper will be needed, but the content can still be reused.

An additional benefit is the concept of conditionality.  Conditionality means the ability to set conditions on when a particular topic or "chunk" will be added to an output.  This can be used to provide customised content to different customers or groups of customers, e.g. standard setup information for a particular sector, or bespoke documentation with a particular customer's or group of customers' configuration in mind.  Once the conditionality is set up in your help authoring tool, new versions can be created at the click of a button. 

Let's take an example.  You work for a company that sell the ACME Budget Software product.  ACME Budget Software is designed to help both SMEs (small-to-medium enterprises) and large companies manage their budgets.  50% of the ACME Budget Software product is intended for use by both SMEs and large companies, 20% just for SMEs, and 30% just for large companies.  Your documentation can therefore single source 50% of the content, and you can conditionally include the 20% (or exclude the 30%) for the SME documentation and include the 30% (or exclude the 20%) for the large company documentation. 

 

What's the Difference Between Single Sourcing and Multi-Channel Publishing?

If you've heard the term "multi-channel publishing" then you might be wondering what the difference, if any, is between that and single sourcing.  There's no concrete agreed answer in the technical communications industry, but this is my take on it (other opinions may vary). 

The single sourcing "output" is equivalent to "channel" in multi-channel publishing.  The difference between single sourcing and multi-channel publishing is that multi-channel publishing can use single sourcing but doesn't have to, whereas by definition single sourcing is designed for multi-channel publishing (and wouldn't have much point without it).  In single sourcing, the content, again by definition, is the same wherever it's published (use of variables not withstanding).  In multi-channel publishing the starting content is the same, but the final delivered content doesn't have to be.  This is particularly so in the case of different delivery mediums such as printed brochures, blog posts, web help, tweets, and so on.

 

What's the Difference Between Single Sourcing and Variables?

Single sourcing uses a block of text (including graphics if required), normally a few lines or more. Examples could range from a two line explanation of a field to a full topic on how to complete a procedure.  This block of text can be used multiple times within a single document and/or in multiple documents.  Variables are a few words, such as a company name, release number, website address, etc, which could change at some point in the future, or need to be different in different outputs.  Variables are embedded in your documentation, and when you change the text of the master variable, the text of the embedded variable changes everywhere in your documentation. If you have multiple outputs you can set the same variable to have different values for different outputs.  An example might be a different Support desk number for standard and Premium users of a product.

Note: I'm using "variable" as a generic term to describe a few words of text that can be placed as many times are you like within a document.  In a help authoring system like MadCap Flare there are both snippets (called text insets in FrameMaker) and variables, and there are important differences between them, but that difference is not relevant to this discussion.

 

When is Single Sourcing Used?

Single sourcing is useful when you have multiple people or teams working on different documentation for the same product.  For example, you might have:

• Technical Writers providing end user documentation;
• Trainers providing training documentation;
• Field Engineers providing implementation and configuration documentation;
• Support staff providing FAQs and knowledge base articles;
• Sales Engineering writers providing tender and demonstration documentation.

In these circumstances, having pre-written and approved chunks of text can save time and effort on the part of multiple people and teams.  This gives a good return on investment for single sourcing.  In other words, the greater the number of target audiences and the greater the number of distribution channels, the greater the advantage of using single sourcing.

But where a team of writers is working collaboratively on the same documentation deliverables, single sourcing is less useful unless you have tightly proscribed standards and structure for the deliverables. This is partly because writers tend to have their own styles, and unless proscribed otherwise what one writer provides will read differently to another writer.  The different styles are not necessarily better or worse, they are just different, but that is jarring for the reader and doesn't allow the reader to develop a consistent expectation of how the document will read.  The other reason tightly proscribed standards and structure are needed is because the content needed in one deliverable could easily be subtly (or grossly) different to the content needed in another document.  This might be solved easily by using conditions, but often the only way to solve the problem is to rewrite the content.  Tightly proscribed standards and structures will either prevent this, or they'll make it obvious before you start a project whether or not you've got existing content that can be reused.

 

Why is Single Sourcing Best Practise?

DITA is a very popular documentation paradigm, and is designed for single sourcing.  This popularity is why help authoring tools normally come with at least some DITA support baked right into the product.  For the proponents of single sourcing, the benefits as listed above make single sourcing an obvious best practise due to the efficiency and return on investment that it provides.  This is a very popular view.  

However, it is not the only view.  There is a view which considers single sourcing to be an inappropriate adaptation of the object-oriented code reuse philosophy, and that view generally holds to the idea that writing documentation is necessarily a different type of creation to coding.  As such, this view sees single sourcing as lacking feasibility in the real world, at least to the point of providing all of the benefits that proponents of single sourcing claim for it.  The most well-known articulation of this view can be found in The Myth of Single Sourcing by Michael Hiatt.  You don't have to choose a side - personally I think single sourcing works well in some situations and poorly in others - but it's always useful to understand the counterpoints no matter which view you favour.