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.
An occasional series looking at best practice for common documentation tasks and situations.
This blog is written for several purposes. Some of the articles are the amalgamation of my experiences that I'd like to pass on to anyone who is interested, and some are articles that help me clarify and explain my thoughts on certain topics within the realm of Agile Technical Writing. These cover the majority of the posts here on www.agiledocumentation.co.uk.
But occasionally, I use this blog as an auto-didactic tool when I'm learning about something new. It helps me to organise and manage the new information and connections; as the old saw goes, "if you want to learn something, try teaching someone else". The subject of documenting APIs is a case in point.
API documentation may or may not come under the heading of "The Basics", depending on what area you write about. My background is software documentation, so being able to grasp the basics of API documentation is a requirement for me. In fairness, the basics are easy to pick up, because the principles are the same for all technical documentation (concision, clarity, accuracy, correct audience target) and the practise is uncomplicated (access, inputs, outputs, effects). However, my experience has primarily been with SOAP web service APIs, which is only one of a number of types of web service APIs, which in turn are only one of a number of types of API. So I decided to brush up on some of the API documentation knowledge that I'm missing, and was planning on writing an article covering the basics that I learnt.
Normally, the process of learning starts with Wikipedia (because its technical articles are normally pretty accurate on the basics and it often has a useful list of links for further research) and moves on to Googling overviews, tutorials, etc. This process can last anything from a couple of hours to a couple of weeks depending on what I already know, and how complicated the source material is to get my head around. Then I write about what I've learnt. Doubtless this is familiar to anyone who writes technical documentation for a living.
However, in the case of API documentation I can't do the subject justice when there is a better resource for my loyal readers, and it's Sarah Maddox's blog. Sarah is a Technical Writer for Atlassian and, as I've come to realise, a doyen of API documentation. I'm not too proud to realise that sometimes there is someone who just knows a lot more than me, and communicates it very well, and in this case Sarah is that maven. Start here for a good overview of API types, and then review her API category for more great articles.
In addition, there's a good article from the Parse blog on this subject, and anyone that uses the phrase "carefully crafted with love" to describe their documentation gets a respectful nod from me. You can also find some great examples of API documentation here and here.
If in the future I find an arcane area of API documentation that could use some elucidation then I'll apply myself to that task, but otherwise I'll leave API documentation articles to the experts like Sarah.....
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.
Example:
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......
