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