If you see documentation as just release notes, user manuals, configuration guides and so on, then you're missing the point and the power of professional writers. Any and all technical information, whether static or dynamic, needs to be shared with or communicated to a disparate community of stakeholders. The more stakeholders, the more critical the need for trained technical writers becomes. Think of documentation as a critical node in the routing of information, and the algorithm that controls that node as a trained writer.
A trained writer understands:
- Writing for different audiences;
- The difference between technical and non-technical language;
- The use of dialects (hint: never use dialects);
- How to avoid idioms, metaphors and analogies that wouldn't be understood by non-native speakers;
- What assumptions can be made about the audience;
- When a piece of writing is ambiguous, and how to make it unambiguous;
- Why short sentences are important;
- How to avoid giving the reader "wall of text" blindness;
- When to use, and importantly when NOT to use, visual aids;
- The benefits of lists and when they're appropriate;
- Grammar, punctuation and semantics, i.e. good writing.
You might think that the expense of having professional writers is not necessarily worth it. After all, a friend of mine who is also a professional writer commented that the quality of writing in 50 Shades of Grey was mind-bogglingly bad, and yet that series of books has sold in ridiculous numbers and inspired a film. Not bad for an author who by all accounts really, really needed an editor. But here's the rub: Sex sells, and in big numbers. Technical documentation does not. If people are reading what you write because they want to, then the quality of your writing is less important. If people are reading what you write because they have to, then the quality of your writing will have a big impact on their understanding, and even whether they read more than a few lines at all.
Doubtless you will be aware that there is a huge difference between listening to an soporifically boring voice and listening to the aural feast of a mesmerising, majestic voice. It is the same with writing. Read One Hundred Years of Solitude by Gabriel Garcia Marquez and rejoice in the fluid, hypnotic intonations and the depth and vibrancy of the picture he paints with mere printed letters on a page. Then read The Most Boring Story Ever Written. Sweet Lord, take me now so that I might suffer it no more. You don't have to be a fan of magic realism to appreciate that Garcia Marquez injects colour and life into his writing in a way that surrounds and overwhelms your mind's eye as you see the story unfold page after page. And yet the story he tells, whilst full of symbolism and allegory, is largely one of family life. As the The Most Boring Story Ever Written makes clear, mundane can be mundane; as Garcia Marquez makes clear, it doesn't have to be.
The same applies, although perhaps with less creative license, to technical documentation. It is not the message that will make your documentation readable, it is the delivery of that message. The message contains the value, the delivery communicates that message. It doesn't matter how valuable the message is if you can't deliver it in a way that your readers can consume. That doesn't mean that your delivery method - help file, PDF, web help, popup, tooltip, annoying paper clip - isn't important, but that's the difference between driving, flying and catching the train. Each one is better in different circumstances, but frankly as long as you take one of them and get where you need to go in a decent time frame it doesn't matter. But driving in a Range Rover is different to driving in a Russian jeep. A professional writer will produce a written delivery that is the Range Rover of communication. An unprofessional writer will produce something closer to a Russian jeep.
At the start of this post, I suggested thinking of documentation as a critical node in the routing of information. But the writers who provide this documentation can be conductors who allow the information to flow freely, or they can be insulators who wrap the information in layers of obtuse and unparseable linguistic murk. Our role as professional writers is, more than anything, to conduct the information as freely as possible. We are not "people who type", or dull people with an insane perfectionist streak for things that no-one else cares about. We are professional communicators who polish our words to a conductive shine so that our readers can get what they need quickly and easily.
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're going to look at direct time costs.
Time is the one thing you can't make back. If you invest £1000, you might make it back if your investment pays off. If you invest 1000 man hours, that time is gone, forever, no matter how the investment pays off. For that reason saving time is possibly more important than saving money, even though as we've discussed previously, time = money.
In Part 3 we looked at an example calculation of ROI on paying for a screen capture tool. That calculation relied on knowing the cost of a help desk consultant and a technical writer per week, but that's not necessarily information you'll have. If you can't use the financial cost saving as your ROI figure, what is the best way to calculate ROI and provide a figure that the decision makers in your company can put a known value on?
Well, time = money (I'll keep hammering that point home), and your management will know how much one person's time is worth and be able to translate that into a financial figure if they want. So really you don't ever need to put a financial cost against someone's time, you can just calculate the time saving and let others worry about working out the financial saving from that. Let's look at an example of a time cost saving with the ROI calculation:
Assume your help desk gets 200 tickets a week, of which 20 tickets (10%) are requests for information about the configuration of the web server that your product needs. These tickets take on average 15 minutes to resolve from start to finish. 15 minutes x 20 tickets = 300 minutes (5 hours). It would take you 10 hours (600 minutes) to write a configuration guide that would answer at least half of these requests for information before they ever get to the help desk. The configuration guide will need to be updated 4 times a year in line with the release cycle, and it will take 3 hours (180 minutes) to update the configuration guide each time. What is the ROI on the work for this configuration guide?
Cost: 600 + (4 x 180) = 1320 minutes.
Gain: 150 x 52 = 7800 minutes
7800 - 1320 = 6480
6480 / 1320 = 4.9
So the ROI for this work is 490% over 1 year. And that's a minimum - remember that the configuration guide will answer at least half of those tickets, but it might answer more, so the ROI might be even better. In future years the return will grow yet again, because the cost will no longer include the 600 minutes it took to write the original guide. The gain that will come from updating the guide 4 times a year makes this idea a no-brainer.
There are innumerable situations and contexts where new or better documentation will be able to save people in your organisation time. When it comes to increasing the ROI of documentation for your product, talk to the people who design it, develop it, test it, market it, demonstrate it, sell it, install it, configure it, administer it, support it and, most importantly because they're the customers, the people who use it. Ask them what they wish was explained somewhere, what questions they get asked the most, what the most complicated or difficult things they do with the software are, which bits of the documentation aren't up to scratch, what documentation they want to have, and then work out how you can create or amend your documentation to answer that question, solve that problem, make that process more efficient, or save someone a job. Because if you want to increase your ROI, you'll have to know what will save people time, and what won't.
I could talk about suggestions for saving other people time with new or better documentation all day, but you know your organisation better than I do so I'll leave it to you to take that idea and run with it. Although this post will be one of the shortest in the series, the concept of improving your ROI by saving people time has probably the most potential for reward, so don't hesitate to do your research and find ways to deliver time-saving documentation wherever you can.
But if you want to write all this fantastic time-saving and ROI-improving documentation, you're going to need some time of your own, right? How do you make that time when you're already neck deep in work?
Hold that thought, because we'll cover it in Part 5.....
An occasional series looking at best practice for common documentation tasks and situations.
Writers who document software will invariably have to document a code snippet or two in their careers. This could range from the occasional line of CSS in a configuration guide every few years, right up to the full-on, nothing-but-code explanations of the full-time API documenter.
I'll be honest, this post isn't for the API specialists, but it is for those who only have to occasionally format a code snippet, or for those who are looking for a better way. Those writers who document APIs will need to follow proscriptive standards and understand the code in order to provide clear, coherent information to their readers. Those writers for whom code is something that people who can't write in a natural language write in instead - you know who you are! (and you're very welcome here) - may however find formatting code snippets a little daunting.
(In case you've never formatted code before, it's not as simple as just changing it to COURIER NEW. Well, it can be that simple, but not if you want to do a proper job. Code snippets will be read by people who code, so it should look like code.)
Fear not, my friends, for there is a simple way to format code.
Your immediate option, if you have access to them, is to use the same tools as the developers. So for formatting SQL you open up a query writer like SQL Server or dbForge Studio for Oracle, drop the SQL into a New Query window, and then copy and paste into your document. You can do the same with code if you have access to an IDE like Eclipse or Visual Studio.
However, the problem with industrial tools like these is two-fold: Speed and Cost. Industrial tools are not built to open in half a second 30 times a day; they're designed for heavy duty coding, and that makes them less than rapid at opening. And although Eclipse is free, Visual Studio, SQL Server and dbForge Studio are not. As I've discussed elsewhere, people should have the licences they need, and it doesn't seem a good use of your budget to spend large amounts of money on licences just so a writer can format code a bit quicker.
Besides, who wants to have to open a SQL application, and an IDE, and an HTML editor, and an XML editor, and a CSS editor several times a day? If only there was a lightweight, fast, free, easy to use application that would open these files with the odd extensions automatically and quickly, and just format the code for us!
Well, there is. It's called Notepad++ and seriously, it's awesome.
If you're not a particularly technical person, Notepad++ might have passed you by, but it is essentially the Swiss-army knife of coding and it is free, lightweight, very quick, and it will format whatever legitimately extensioned code file you give it with ease. Well, let me rephrase that: The list of programming language file extensions it supports is very large, and the chances of you working on one that isn't supported by Notepad++ is low. All you have to do it right-click a file and Open with Notepad++ - or set Notepadd++ to be the default program for opening the code files you need to format - and it'll do the rest.
Here's an example .xml file opened in standard Notepad:
And exactly the same file in Notepad++:
That is out of the box, default functionality. I created a new text file, wrote some XML in it, saved it, renamed the file to XML.xml, and opened it in Notepad++. All you have to do at this point is cut and paste the code into your document, and you're good to go.
I'll come clean with you on one thing: If you want it to auto-indent code that hasn't already been indented, you will need to install a plugin. But that's not too tough an ask, especially if you deal with existing, indented code. By default Notepad++ will change the indent of the TAB button to the standard indent for whatever code you're working in, so as long as you haven't got long screeds of unformatted code to work with, indenting it yourself is very easy. There is also a very active user community, as Notepad++ is used by millions of people around the world, so if you have questions there's a good chance the answer is available already, or someone will answer it for you if you ask on a forum.
If you've got another tool which you think is as good as or maybe even better than Notepad++, please share it in the comments.
