Improving Documentation ROI: Part 5 - Saving Yourself Time

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're going to look at ways to save you and your writers some time.  Specifically, we're going to talk about the following areas:

• Passive income (templates, single sourcing, etc) 
• Production line efficiency (procedures, standards, etc)
• Personal efficiency (time/task/email management, saying no, etc)

So as not to confront you with a wall of text, I'll split this up into 3 articles, starting in this one with passive income.


One of the ways to increase your revenue is to have what is known as a passive income.  This is where you create something once and it makes money for you 24 hours a day without you having to do anything.  An example would be writing an e-book that people can buy from anywhere in the world 24 hours a day, 7 days a week, 365 days a year, without you having to do anything except file your tax return once a year.  The same principle can be applied to reducing time costs by the one-time creation of things that will save you time in the future.   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. Consider it a passive time income, if you will.  Examples for Technical Writers might include:

 - Templates - If you create the same type of document on a cycle (e.g. every sprint, every release, etc) then consider creating templates.  These will save you, and anyone else in your team who creates the same kind of document, time in every cycle.  There is also the added benefit of ongoing consistency and a single place to make changes for all future versions of the document.

 - Single sourcing - Some documentation, or parts of a document, can be used in multiple places (e.g. information in the release notes will also go in the help file, or instructions in the installation notes will also go in the configuration guide) or at multiple times (e.g. multiple minor release notes can be rolled up into a single major release notes document).  Single sourcing can be done by using help authoring tools like MadCap Flare to create individual pages that can be added to or subtracted from whatever target (i.e. document output) you specify. In these circumstances single sourcing will prevent you having to rewrite/copy the information, and all the attendant review processes that are implied by what is essentially the production of new documentation if you have to write it again.

 - Variables in your help authoring tool - All help authoring tools have the concept of variables (or something similar) which are used to place text in multiple places in your documents.  Changing the master variable will change it in every place in the topics you've used the variable in.  This is extremely useful for things like release numbers, company details, support desk contact information, etc.  Not only do variables prevent you having to do a search and replace across one or more documents, they also ensure consistency of text, so you know that as long as the variable is correct then that text will be correct everywhere that the variable is used. As an added bonus, you can usually set up a master project with variables and other elements in it, and import this data into new or existing projects so you don't have to set everything up each time.

These are a small sample of the possible ways you can reduce your time costs by using the "Create once, use many" principle, so inspect and adapt to fit your situation.  

The ROI for this kind of future time saving is as follows:

Cost = Time taken to create template/variable/whatever;
Gain = (Number of times the template/variable/whatever is used) x (Amount of time it would take to create the template/variable/whatever from scratch).

Example:

Time to produce a blank release notes document ready for the release cycle: 15 minutes.
Number of release cycles per product per year: 6
Number of products: 4
(i.e. 24 blank release notes documents are created each year)

Time to produce a blank release notes document template: 60 minutes
Time saved per template usage: 10 minutes (it still take 5 minutes to copy the template, add the release number, remove unwanted sections, etc)

Therefore:

Cost = 60 minutes
Gain = 24 x 10 = 240 minutes

ROI = (240 - 60)/60 = 3 = 300%

Bear in mind, as ever, that if your templates can be used each year with minimal or no tweaking you'll keep reaping the rewards year after year.

The simple maths indicates that you will save 3 hours a year, which might not seem like a massive amount.  But there is an economy of scale here, and the more documents you can create templates for, and the more writers who use them, the greater the saving.  There is also a hidden reward in that as long as the templates are right, your review process will be slightly shorter, and the number of errors that you need to fix will be lower.  (There are also the benefits of consistency for both the writer and the reader, but as this post is specifically about saving time I won't dwell on that).



Use the passive income technique to save your future self time in any situation where you could simply clone something, by creating the clone.  In part 6, we'll look at the time that can be saved by using some production line efficiency.

Vanishing Standards?

The following comment was posted on LinkedIn recently by a fellow professional called Rupen:

"Recently, when looking for a Senior Technical Writer, I interviewed many, many participants with terrific CVs. I noticed that most did not follow basic writing principles; I try and adhere to the Chicago Manual of Style. They could write, but were unable to present information in a digestible manner. Each person seemed to have learned the principles once-upon-a-time, but after many projects, the principles vanished and delivery was more important. I wonder if this is because many companies have adopted Agile documentation practices.

I concluded that most people working as Technical Writers aren't really passionate about the field. They are makeshift technical writers, who'd rather be doing something else. It annoys me because the broader world of information experience deserves more respect.

...needed to vent!"


Rupen's conclusion that "most people working as Technical Writers aren't really passionate about the field" strikes me as incorrect, but I understand his frustration, as did many other people on the thread.

I've also seen the problem that he faces, but the issue wasn't that the writers didn't care, it was that they either didn't know about style ("how to write") or their experience was that they didn't have time - nor any pressure - to write to a specific style.  Where Rupen is spot on is his assertion that "the broader world of information experience deserves more respect" (also, +1 for the previously unknown-to-me "information experience" phrase).  This is the key to the problem, and it says to me that the candidates who don't know about styles are a symptom of a problem, not the problem itself.

I'll come back to that, but first a quick note about Agile documentation practises, because it's important that we don't conflate a move to Agile with a change in writing standards.  Agile does encourage "just enough" documentation, but that doesn't preclude high quality, consistent output.  It depends on what "just enough" means to the person responsible for setting the documentation standards, and also the documentation goals of the company employing the writer.  That is the same in real terms whether your company is Agile or not.

But back to the problem of which Rupen's candidates are a symptom.  I see 2 main issues which have caused a degradation of standards:

1. An industry culture that assumes a documentation cost rather than a documentation value.
2. An explosion in tech companies that need documentation.

Documentation Cost

Every writer has worked for companies that don't particularly value documentation, and in these companies the Technical Writing function doesn't get the resources, leadership, or, sadly, the respect that it deserves. This problem is very visible when it comes to things like standards, and the consistent application of those standards.  A move to Agile can be an excuse to do away with any gains that the Technical Writers may have made in this area, often by disseminating common misconceptions about the importance, or lack thereof, of documentation in the Agile process and using this as an excuse to end "expensive" things like peer-review and proscriptive standards.  Some of these misconceptions are dealt with here.  But a move to Agile doesn't mean that this WILL happen, just that it can happen.

I've said previously that this perception of cost rather than value is one of documentation's big strategic, structural problems, so I won't go over old ground too much.  But it speaks directly to Rupen's experience because a lot of companies don't want to put the resources into documentation, unless they're serious players like IBM or Microsoft.  

Part of this cultural problem - and it is cultural, because the benefits of documentation are legion and obvious to anyone with an ounce of common sense - lies in the fact that most tech companies are started up by developers, and most developers hate writing documentation.  That might seem like a trite observation, but how many tech companies have a developer right at the top?  A lot of them.  And by the time they sell to Google or Facebook or Microsoft or whoever, the culture is set and the technical debt in documentation is almost too large to be sensibly paid.  Which brings me neatly on to point 2.

Lots More Tech Companies

Since Sir Tim Berners-Lee invented the World Wide Web in late 1989, there has been a profound change in the pace of company growth.  Companies like Uber, Square and Pinterest, with virtually no staff or bricks-and-mortar resources, have achieved in a few years a market capitalisation that took traditional companies decades to reach. The WWW and the underlying infrastructure of the internet have brought about the biggest single democratization of wealth creation through creative ideas in the history of mankind.  Isn't that awesome?  Can I get a high five?  Yeah, high five.

Now, not that I want to burst that bubble, or make it all about documentation, but democratisation does have some drawbacks.  One of those is the lack of command-and-control.  Dijkstra would be turning in his grave if he knew about all of the code out there that he would consider harmful.  If we had command-and-control, or at least trained dinosaurs:

High Five?

Then this could be controlled.  But the WWW is a democracy (or Wild West, depending on your preference), so it can't be controlled.  The explosion of tech companies has meant that there just aren't enough writers with experience of documentation good practise, like proscriptive standards, principles of consistency, a lack of dialects, and so on, and those that have it often coagulate in bigger companies that have been around for a while.  This is because those companies are prepared to pay time and money for high-quality documentation, and writers who've worked in that kind of environment are often loath to leave for the chaos of a much younger company where they will spend most of their time explaining why documentation is important.

I've interviewed many people who have experience of working with tech companies I've never heard of, and when you look up those companies, a lot of them are 10 years old or younger.  As documentation is often one of the last things to be properly implemented, is it any wonder that these people haven't used, or maybe ever seen, decent standards, processes and procedures?


In summation then, lots of tech companies, created by people for whom documentation is an afterthought, combined with not enough experienced writers, means a lack of credible candidates.

Whatever the cause of this problem, I'll say one thing:  Everyone I know who writes for a living does it because they are passionate about it. It's up to those of us with some experience to teach them what they need to know to turn their passion into good documentation. Bang the drum, people!


 

What Day Should a Sprint Start on?

This is the kind of question I like: Sensible, thoughtful, and with an easy answer.

Your sprint should start on a Tuesday or a Wednesday.

To provide some justification for that confident answer, here are some important requirements for your major sprint ceremonies:

• You need your whole team in the sprint ceremonies as often as possible.
• You want your sprint ceremony days to be as regular as possible (i,e, to fall on the same day of the week on every sprint). 
• You need 2 consecutive days, 1 for review and retrospective at the end of the last sprint, 1 for planning the new sprint.
• You want your team to be focused and alert for both of these days.

I think we can all agree on these basic requirements.  Here's how they affect the days of the week your sprint should start on:

• More holidays (and sick days) are taken on Mondays and Fridays than Tuesdays, Wednesdays and Thursdays.  So if you want your whole team there, the chances are much better on a Tuesday, Wednesday or Thursday.

• Public holidays (especially in the UK and some other Commonwealth countries), tend to fall on Mondays.  In countries that have a Christian history, Good Friday and Easter Monday always - obviously - fall on a Friday and the following Monday. This means you are almost certain to lose one or more ceremony days to a public holiday.

• Fridays are the day people are least likely to be alert and focused, and the day they are most likely to be thinking about leaving early (if your company has flexi-time or similar).  That makes Fridays a bad day to have either reviews and retrospectives or planning meetings.

• More discussions of weekend shenanigans, sporting events, hackathons and whatever else people get up to, happen on a Monday morning than any other time of the week....except possibly Friday afternoon.  This does not lend itself to an alert and focused mental state on either day

• Monday morning is often used for start-the-week meetings, email catchup, and so on.  This will interfere with ceremony timing, or, harsh but true, the ceremony timing could be seen as interfering with "normal business".  This is particularly important if you are still trying to get buy-in for agile at your company.

Ceremonies are supposed to be time-boxed, and everyone should be working their full hours every week (baring holidays or sickness), but let's be realistic about how people really are.  We are not automatons, we get more tired as the week goes on, we have a life outside of work, and most of us get on with at least a few of our colleagues and like to talk about our weekend.  This is normal. It's not wrong, it's not weird, it's not lazy, it's how humans are.  Make sure your Agile implementation takes that into account, and schedule the start of your sprint on either a Tuesday or a Wednesday.  You'll get a lot more out of your team if you do.