- Improving First Run Quality
- Revision, Waste, and Evenness
- Reducing writer errors
- Dumb vs. Smart Revision
A couple of weeks ago, in a post titled Improving First Run Quality, I cause a kerfuffle, and some questioning of my sanity, by suggesting that rather then celebrating revision as an essential part of the writing process, we should regard it as a sign that the writing process is flawed.
Today I wish to expand on this idea that we should be regarding revision as a bad thing. One of the key principles of lean thinking, which takes it inspiration from the Toyota production system, is the reduction of waste in the production process. Waste is anything that does not add value to the product. Rework is waste. If work is done, and then has to be done again, that is wasteful. Revision is rework, therefore revision is waste.
Technically, it is the original work that had to be redone that is the waste. The rework sets things right, and therefore does add value. But the original defective work was waste and did not add value. Rework, then, is the sign that waste is occurring earlier in the production process.
When you find something broken that needs to be fixed, of course you have to fix it. If you find content that needs to be revised, of course you need to revise it. Revising isn’t bad, but it is a sign that something bad has happened. It is a red flag that wasteful work occurred earlier in the process.
So, when we find ourselves revising, we should be asking, why was this content not written correctly in the first place? There could be many reasons. Lets examine a few possibilities:
- The product specification changed after the content was written.
- The writer misunderstood the subject matter when they originally wrote the content.
- The content was written by a subject matter expert who did not know what needed to be written or did not write it well.
All these things happen regularly in tech comm. We respond by revising. We accept the fact of the wasteful first effort and move one. Should we be accepting it, or should be be asking why the wasteful work occurred in the first place, and thinking about how we could avoid that waste in future?
In the first case, the product specification changed after the content was written, there are several questions we could ask, like:
- Was the content written sooner that it needed to be? Could it have waited until the specification was more stable?
- Could the specification process itself be changed so that it creates less rework in both development and tech comm?
- If we had a more systematic approach to documenting these things, might we have caught the problem in the specification earlier?
In the second case, we could ask things like:
- Is the correct writer being assigned to the task?
- Are we using the right criteria when hiring writers?
- Are we paying writers too little, meaning that writers who understand this technology are not willing to come work for us.
- Are we not providing writers with the equipment and access they need to learn the technology?
- Are developers unwilling or unable to help writers when they need it.
- Does the writer know the right questions to ask? Do they know what users typically need to know about this subject? And if not, can we help them by providing a structured writing environment that prompts them to provide the required information.
In the third case, we could ask things like:
- Are we assigning the writing task to the wrong employee?
- Could we improve the content the SME creates by giving them a form to fill in?
- Could we extract the information we need from the code itself rather than asking the SME to write it down?
Another important thing to ask when we find ourselves revising is, could this have been caught earlier? It is one thing to revise in response to a change in the specification at the time the change occurs, and quite another to have to revise weeks or months later, or after the product is in the field and a customer is losing productivity because of the incorrect information.
Content in need of revision is content that contains a defect. It has been shown in multiple studies in multiple fields that the expense of fixing a defect grows exponentially the longer the defect goes undetected. Detecting and fixing a defect immediately is usually cheap. Finding it and fixing it later could cost thousands or even millions. One of the most important questions you should ask when you have to revise is, how long ago was this defect introduced into the content, and why didn’t we catch it sooner.
A revision, therefore, may be a sign that your quality control processes are poor. One of the biggest problems in quality control processes is often that they simply occur too late in the process. If you write an entire book before you send it for review, then you have a very long-cycle quality control process, meaning defects are not detected promptly, and your quality control will be poor for several reasons:
- The writer who created the content defect because the misunderstood the product will have continued with that misunderstanding as the wrote other content, meaning it too has to be revised. If their content is being reuse, the defective content may be in several places. If test uses documentation to create tests, the tests may be incorrect. If training uses it, the training could be bad. If sales uses it, false customer expectations could have been created and possibly even contracts rendered invalid.
- The longer between the time the engineer developed the function and the time they review the doc, the less clear their memory will be, and the more likely they will miss the defect, which will only further increase the time before it is discovered and the cost of correcting it.
- The more stuff you give the engineer to read at one, the more rushed they will be and the worse job they will do, with the same consequences.
The agile development approach is sometimes criticized for creating rework by not rigorously defining the specification of a product up front. But what agile is really designed to do is to decrease the amount of time it takes to detect errors in the specification itself, and thus reduce the cost of specification errors. An error in the specification in a waterfall development process may not be detected until months or even years later, after the project has been finally delivered to the customer, and the cost of fixing it at that point can be astronomical.
Of course, the iterative development that agile practices, can result in rework, and rework is waste. But there are times where some waste is inevitable. Sometimes you need a prototype to test the specification, and if the prototype reveals a defect in the specification, then the prototype will have to be reworked. That is still waste, but it the lessor of the two evils compared to not testing the specification until final delivery. Similarly, there can be revision of content that is unavoidable because it results from a need to test the specification, or for some other unavoidable reason.
Even so, it is still waste. And a lean process is never satisfied. It may accept that it is useful to trade waste in one area to avoid waste in another area, but it still seeks for perfection. It still bids us to ask, can we further reduce waste here without increasing waste over there?
This brings us to another property of a lean system: evenness. One of the keys to lean thinking is to look at the overall production flow and strive for evenness through the whole production process. Sometimes optimizing one part of the process introduces unevenness in the other parts of the process, creating more waste than it removes. The point, then, is not to optimize the writing process by removing all occasions where revision might occur, even if it disrupts the rest of the development process. The point is to recognize that a revision is always a sign of a defect introduced earlier in the process, and that the source of that defect should always be investigated.
We may never remove all revision from the writing process, but we should always see it as a sign that our process can be further improved.
I’ll talk more about this in my LavaCon 2013 talk entitled More Content in Less Time, which looks at the application of Lean and Agile techniques to the production of content. If you want to chat about how you can apply these methods in your organization, feel free to contact me.
Excellent points, all, Mark, especially the part about revision being inevitable, despite all attempts to minimize it, and the application of lean and agile processes to writing.
There is one other case, however, that you haven’t dealt with: editorial revision that has, as its objective, not the correction of errors, but improved quality. In other words, sometimes we have text that is OK – it is correct, reasonably clear, and publishable. But we can make it better. By “better,” I mean that we can perhaps reduce verbiage, improve accessibility, or craft the language so as to make it easier to translate and localize.
None of these processes represents a defect, but rather, an improvement in quality.
The question then becomes, “how much quality do we need/want, and at what point does quality improvement become an unacceptable cost penalty?”
I suspect that the answer to these questions needs to be done individually by each company as part of their process and methodology controls and SOP’s. And these questions don’t only apply to writing, of course.
Thanks for the comment, Ray.
Yes, improvement of editorial quality is a separate case. It is not an error, but I think it is still a defect. If an editorial revision is needed, that is because the original copy did not meet the applicable quality standard. So it is still a defect, though one of lesser importance.
Another case of waste is when an editorial improvement is made to copy that already meets the applicable quality standard, either because of stylistic differences between writer and editor, or because the editor is applying a higher quality standard than is actually required.
Both these cases are waste, and should be investigated. The difficulty, of course, is defining editorial quality in a measurable way. Structured writing practices can help, as can tools like Acrolinx, if appropriately used. But it remains a hard problem.
Speaking of defects, I misspelled my own name in the above comment.
Rework.
🙂
My personal opinion about revision is, that it is a completely useless step in production of content.
What I learned over the years is, that the only ones judgeing your documentation should be the ones it is written for. Everybody else that is part of the development process or the documentation process, is not qualified for reviewing your work. Sounds strange, but there’s a lot truth in it. You never wrote for them as they have either no relationship to the product (your fellow colleagues) or are involved too much (developers and product managers). All they will add in a review process is more confusion, useless information or changes of formulations. Nobody needs that.
If wrong information made it into the documentation, something went completely wrong in the research process. Either you got outdated, wrong, misleading or incomplete informations.
As tech writer (at least this is how I see it) you don’t have to be an expert in the tech you’re describing, it is sufficient if you are able to understand the developers – it is their job to explain things upfront to you. Everything else is researched in the process of writing anyways.
Maybe this is just my frustration, as I just went through a review hell with a customer of ours, but I’m pretty sure there’s enough truth in it to be valid o a point.
Thanks for the comment, Alex.
I know where you are coming from. Few of the people we ask to review content are competent to judge whether it is fit for its intended purpose. (One of the issues with minimalism, I believe, it getting it through a review process.)
On the other hand, if the only test point in the process is after delivery, that means defects will persist a long time before they are found, and thus be expensive to fix.
This suggests that we should be looking at alternate approaches to content validation, as well as, or instead of, engineer review.
Alex, although I think you express your frustration in a rather extreme tone, I do think you are right. One of the traditional traps for tech comm is that writers have almost never had access to the customers/users/learners for whom they are writing.
This has, fortunately, started to change, especially in the context of agile development, but there is a long way to go.
I also take Mark’s comment that we need to be looking at alternate approaches to validation. I would propose that what is needed is the following:
-Engineers or developers can only say “true” or “not true” in their evaluations. Good lord have I seen engineers who want to correct my grammar (sometimes incorrectly) and don’t say anything about the technical validity of what I have written. True or false. Binary. Engineers should understand that.
-In order to avoid the problems that Mark points out – we should be including in our content development life cycle a real-life usability testing phase right after first draft. With real customers, not the favoured ones who habitually get advance releases and beta access. Doing it at first draft also gives us a reality check on the true or false validation from SME’s. doing it at first draft stage means it’s done early enough to catch defects in early stages.
What do you guys think?
This is more or less exactly my thought, too.
But I would stretch it farther and dare to say, that the only ones revising our writing should be the customers you mention. But not in the way we are used to (sidenotes, comments, you know). I gladly had the chance to interview some random customers a few times, which classified my documentation as bad. Talking to them revealed, that it wasn’t the existing content, that bothered them, it was the stuff that had been taken out by revision in the first place (“inappropriate, confusing, not leading to a point,…”).
This is also why I hate reading my own documentation (mostly): it is revised to death. All the nonsense that is explained, nobody cares about. All the little things that annoy a reader (no index, stupid text/picture relations,…). All the descriptions of features nobody needs or wants. You get the point, I guess.
To an end user, documentation needs to be two things basically: How do I get the damn thing to do what I want? and: How do I get it fixed when it’s messed up?
Revision that is out of the context of the user of the documentation is quite useless in my opinion. You are quite right when you go with the binary proposal for engineers, but I would stretch it further and dare to say: this should be the only way of revising your content in house.
Alex, for your comment as “Revision that is out of the context of the user of the documentation is quite useless in my opinion.”, I am not sure of the role and place of international technical writing standards and adherence to common style guides, such as MSTP.
If different documentation teams start using their own judgment to setup quality benchmark primarily for ‘user context’, and if they formulate the revision process specifically for ‘user-context’, I am sure this will add too much variety to the common internationally accepted writing conventions and guidelines, and hence dilute these. (A common example is use of present tense of active voice in the instructions.)
If user-interaction suggests that instructions are poor, incomplete or boring and images make little sense, then this is the issue with writing process itself, and axe should not be directed to revision process. However as I said in another comment, efforts should be directed to eliminate the reasons that escalate the revision time as much as possible.
Alex, again I sympathize. But I want to look back into the process and try to figure out how we more consistently meet user needs once we have discovered and understood them. Relearning the same things over and over by interacting with one generation of customers after another is wasteful.
As I noted in my reply to Ray, I think we have to focus on patterns. These patterns will likely be specific to our product and to our customer’s tasks — they are not generic or even industry wide. We should be using our customer interactions to discover the patterns that work, and then using structured writing techniques to produce content that consistently and reliably conforms to those patterns.
One of my ongoing grievances is that structured writing has largely been employed for reuse and publishing tasks, ignoring what I believe to be its primary purpose, capturing the information design patterns that work best for our readers.
Thanks for the comment, Ray.
Certainly moving testing as early as possible, and as close to the user as possible is key to reducing waste in content development. If your are lucky enough to work in a real agile development environment, you should have the opportunity to make frequent deliveries to customers, though of course this is not in itself a usability test.
But usability testing is expensive, probably too expensive to do for every piece of content every time. What I would like to do with any usability testing opportunities I get, it to test patterns rather than individual content objects, then use structured writing techniques to reproduce the patterns that work best.
Mark,
These suggestions for reducing waste could make quite a difference in the writing process. I’d love to see some of these improvements put in place. At the same time, I wonder how this revisionless model accommodates certain things.
For example, you recently referred to revising your own book. In a revisionless model, would authors not need to do this?
In anything I’ve ever written, even if I have a lot of knowledge to begin with, I learn more as I go, partly from researching, partly as I get feedback from reviewers. Something new becomes clear: revision makes the doc better. In your model, what are the allowances for the author learning along the way?
I also wonder how this model accommodates the sheer difficulty of successful communication. You wrote recently that some of your blog followers read the opposite meaning into your title than you had intended because they didn’t see its irony. Writers, like everyone else, are up against what’s often called the “curse of knowledge”: once we know a thing, it becomes impossible to remember what it was like not to know it, and so it becomes difficult to get information across clearly to people who don’t share that knowledge. What the author may think is clearly stated turns out to confuse people. Revision can rectify the confusion. How does your model accommodate the “curse of knowledge”?
Thanks for the comment, Marcia.
What I am proposing is not strict a revision-less model. It a model that says a revision is the result of a defect, and we should look for the cause of the defect and remove it. Don’t just fix the defect, in other words, but fix the cause of the defect.
Simply stopping doing revision, without eliminating the defects that require revision, would obviously be disastrous.
The biggest round of revisions in my book were really caused by me not trusting the reader. I did spend some time thinking about why the original organization did not work, and hopefully I will not make the same mistake the next time. I don’t believe for a moment that we can eliminate all mistakes, but I do believe when we make a mistake we should try to figure out why and how not to make the same mistake again. I like to say that I try to make sure all my mistakes are original.
The question you are about the curse of knowledge is a good one. But it is one I think we should seriously study. Maybe we need to have every writer spend one month on the tech support lines each year to keep them in touch with the users.
My point in all this is that we have got into the habit of assuming that revision is natural, inevitable, and good. And it’s not. It is a sign we made a mistake somewhere, in the process.
In software development, it is acknowledged that there will always be bugs, but nobody regards bugs as a necessary or virtuous part of software development. Software development experts spend lots of time and effort looking for ways to reduce the number of bugs created and to catch them earlier. Practices like pair programming and test-driven development are some of the outcomes of these efforts, and the work to substantially reduce the number of bugs created, and allow them to be caught more quickly.
Content development needs to be similarly dedicated to reducing content defects and finding them sooner. It’s not about eliminating revision tomorrow, it’s about ending our complacency about it.
“My point in all this is that we have got into the habit of assuming that revision is natural, inevitable, and good. And it’s not. It is a sign we made a mistake somewhere, in the process”
No, it is not. Things change. The world is in flux. What looked perfectly understandable yesterday looks like jibberish today given what we have learned in 24 hours. We make constant and minor course corrections as we go, not one hard left once we start scraping the iceberg.
Thanks for the comment, Debbie. I have to disagree though. We are not orphans in the storm, or, if we are, it’s our own fault.
The World does change, but we are not the helpless victims of those changes. We can anticipate most of them, and plan for them, and we can create a process that minimizes the impact of changes, both those we anticipate and those we don’t.
I think there needs to be a nuance here. Some writing — like books, some procedures, I could go on — is going to need revision no matter what amount of thought or time goes into the initial writing process. Most of the revision I do at work involves work processes changing over time — the people actually doing the work finding more efficient ways to do the work and needing a change in the writing to reflect those efficiencies.
It’s the same with a fantasy novel I’m writing. If I let it go at the first draft, well, yuck. Books aren’t written on a yardstick, but rather resemble the ripples in water after you’ve dropped in a rock. Some of those ripples bounce off obstacles and come back into your field of vision, moving in directions contrary to how the initial ripples voyaged out from the point of creation. Revision doesn’t always mean wasted effort — it sometimes means the addition of additional effort.
Thanks for commenting, Brian.
Yes, we definitely need nuance. In the case of a change in subject matter, of course a revision is needed. On the other hand, we could look on that no so much as revision of the old, are reuse of the old to produce the new.
If fiction, in fantasy in particular, you are world-building, and you may write as a means of world-building. Tolkien did this in volumes. Tech comm is not world-building. It should be possible to exercise more control over the process. In any case, most fiction writers are self employed and may spend their time how they will. For a time and resource constrained tech pubs department, however, curbing waste is an immediate practical problem.
While writing, a writer invariably knows that we shall have time to revise even if a dedicated revision time is not allocated explicitly in the documentation plan. Does it mean that this ‘scope of revision’ gives us a false sense of security when we are writing that we can always review or revise later? Many other professionals cannot afford to revise their work because there is no scope. For example, a chef cannot revise a dish and add or alter an ingredient later after the dish is complete, or an architect cannot offer to move the hedge by 2 units inside after the ceiling is ready. So can we say that we are fortunate to have this luxury, to get to review our work?
I reviewed Marcia’s book ‘Word Up’ few days back and I specifically reviewed a chapter on revisions, at: http://enjoytechnicalwriting.com/2013/07/27/of-word-up-how-to-write-by-marcia-riefer-johnston/. I re-read that again today and I completely agree what Marcia says about revisions. I will add that we should find the ways to reduce the time that we spend on revisions. It means identifying all those reasons of what we needed to revise and then eliminating those reasons.
Vinish,
Once again you bring cooking and writing together beautifully. Thinking about the cook’s inability to revise a dish reminds me that I often feel thankful to have chosen a career in writing rather than surgery. “Oops, took out the wrong organ” has a way of putting people off.
I’m glad that my chapter on revising (actually, “re-vising” as in “seeing anew”) resonated with you. I believe that revision cycles add value for readers not only because mistakes get fixed but also because useful writing, like useful software, results from iteration. Good writing (by which I mean writing that leaves readers feeling well served, however the reader defines “well served”) involves too many factors for any writer–no matter how skilled, no matter how steeped in the subject matter–to nail the first time around. To equate all revision with waste is to belie this reality.
I like your phrase “we are fortunate to have this luxury.” In a business model, of course, revision must stay within the boundaries of what’s worth paying for–a tricky boundary to determine. (That topic deserves its own separate discussion.)
I do agree with both you and Mark about the opportunity that companies have to make the writing process more efficient. Mark’s lists of questions above could take any company a long way toward eliminating unnecessary revision from their processes.
Thanks for the comment, Vinish. I love the analogies to architecture and cooking, and I think you are absolutely right that writers have been living with a false sense of security, thinking that they can always revise to get things right. The problem is not that you can’t revise, but that revision is expensive. With budgets what they are, we cannot continue to be complacent about those costs.
Perhaps the distinction should be between “dumb” and “smart” revision.
If we are evolving an existing suite to fit the goals of “Every Page is Page One”, that’s going to involve a lot of revision.
“Dumb” revision would be to go ahead and revise every topic to fit the goals. “Smart” revision would be to prioritize every topic according to and end user usefulness metric.
Either way, revision will be required.
Further, in making a transition to “Every Page is Page One” writers creating new material will have to go through a longish re-training or training phase. The most effective training will be to have their material edited by a third party and then have the writer revise their writing. This gets tiresome so most writers so they will quickly adopt the new standard.
So, I disagree that the need for revision implies the existence of a defect. The need to revise is most often, I think, driven by changing circumstances.
However, if circumstances have not changed (including budget available for quality assurance) then text that is published and then needs revision is indeed wasteful and a most likely a systemic failure.
So as usual when reading Mark’s stuff, I agree and disagree.
Well done Mark and thanks for the post.
Thanks for the comment, Peter.
Yes, some distinction between good revision and bad revision certainly needs to be made. One of my pet phrases is “all language is local”. We draw on a common stock of words to make the distinctions we are interested in. When one attempts to make a new distinction, there is never a vocabulary for it.
One way to make the necessary distinction might be to avoid the word revision altogether, and to use the term “rework” for revising writing to better serve its original purpose, and the term “reuse” to mean adapting existing content to serve a new purpose.
Reuse is not waste; rework is waste.
Mark,
A definition of the term “revising,” as you mean it here, would bring your post into sharper focus for me. In the largest sense, revising (making changes) happens constantly along with writing. For example, I just bumped this paragraph up from the end, where I had written it at first. I suspect that when you say “revising,” you don’t mean that kind of revising. (When I talk about revising in my chapter, I do include this sense of the word, as in the kind of “sketch thinking” that architects do.)
Similarly, when a writer circulates a rough draft for feedback and then makes changes accordingly (to clarify confusing passages, to discover the need for definitions, etc.), I suspect that you’re also not talking about that kind of revising.
So I’m curious. In a business context, where do you draw the line between writing and revising?
And how about outside the business context, say, with an author’s own book?
Great questions, Marcia.
First, I would invoke the distinction I made in my reply to Peter about rework vs reuse. But you raise another question: how much reworking of material occurs as part of the act of writing itself?
Good writing has a shape to it, and revision-while-writing is the process of discovering or inventing the shape of the piece we are writing. Our modern habit, enabled by our modern tools, is, to use Leigh White’s phrase, to “write outside our heads”. We don’t figure out the shape in our heads and then transcribe. We put the bits and pieces of ideas out on the screen and then move them around until the proper shape emerges.
Is writing inside or outside of our heads more efficient? I have no idea. But I think in tech writing, where we are creating many similar pieces on many similar topics, reinventing the shape each time is definitely waste. Which brings me back again to structured writing and the creation of testable, reproducible design patterns for content.
So, the process of revision by which we develop a pattern may not be waste (though it may be done using a wasteful method), but to discover the same pattern over and over again is waste.
It’s simple: Perfection takes more time than a development cycle.
That said, most people in the industry today are too young to remember and know the value of a good editor. Editors added tremendous value for work done on short turnaround.
Thanks for the comment, Steve.
I think we have to have other benchmarks besides the current situation and perfection. By changing our processes, we can produce higher quality in less time. Revision is one of the indicators that there may be an opportunity for process improvement.
I agree about the value that editors bring. But there are other techniques we can use to improve conformance during the writing process itself. Whether it is wise to dispense with editors altogether is a different matter, but the fact is that most groups have dispensed with them out of budgetary necessity. So we need to look for other techniques of improving and auditing conformance and quality. People with editing skills could play a significant role in designing and implemented such tools.
You have a defect in your article. How will you deal with that? The sentence reads: “It has been SHOW in multiple studies in multiple fields that the expense of fixing a defect grows exponentially the longer the defect goes undetected. ”
I’d love your thoughts.
Thanks for the comment, L Kim. I have fixed the error. Thanks for pointing it out.
Writing a blog post is very much an artisan task. It is not clear to me, at the moment at least, how I could usefully apply industrial methods to an activity like this.
One the other hand, if I could find a blogging tool with a more advanced grammar checker, it would help catch this category of mistake.
In general, I think, one of the problems with have today is that we have too many add hoc editors for different purposes, all with different feature sets. A more general separation of editing from publishing functions would help move us towards a situation in which we could use one editor for more purposes. But that means structured writing, and current structured writing approach as too heavyweight for purposes like blogging.
Indeed, the complexity and difficulty of current structured writing approaches is a major stumbling block to the creation of more efficient content development practices.
How is writing different than creating a product? I shudder to think of products–cars, refrigerators, airplanes–being released after a first pass. Mark, I agree with your premise about the three reasons rework often becomes necessary, plus I’d allow for a couple additional reasons that were mentioned in the reader comments. But in a perfect world, if all those reasons disappeared, I’d still want to allow time for a review/revision pass. You can be a top-notch writer and still benefit from other perspectives. As for the reader who thinks other reviewers, except users, are not qualified to review a writer’s work, I disagree. Sure, I’d love to be able to tap into the user base for reviewing my work, but when that isn’t possible, you can still get valuable input and review from people in an organization who work closely with customers (e.g., trainers, customer support folks, etc.).
Thanks for the comment MJ.
There is a story in the lean literature (I think it is in Lean Thinking, but I’m not sure) which compares the Toyota production process with the old Porsche production process. Porsche never stopped the production line for a defect, but they had an extensive testing an fixing process after each car came off the line. This mean many cars were being fixed by hand after they came off the line. This was expensive and it tended to miss things, so Porsches tended to have high rates of defects reported by owners, which had to be fixed under warranty, thus further driving up costs.
Toyota, by contrast, always stops the line when a defect is discovered, and always does a root cause analysis of a defect. The result is that very few defects make it through the production process, and extensive testing and fixing is not needed.
So, you want products that are released after the first pass, as long as the producer is focused on perfecting the manufacturing process. This will give you higher reliability that if the manufacturer is testing and fixing everything after production.
I do agree about the value of feedback from many sources. But do we always have to get the same feedback from the same people for every document we create? Or can we bake the lessons learned from that feedback into our content creation process so that we don’t have to go back to those same people over and over again?