January 15, 2010

Agile Tenet #10 – Simplicity is Essential

Filed under: Uncategorized — heratech @ 3:23 pm
Tags: ,

Jersey number ten Tenth in a series of posts examining the Twelve Principles of Agile Software and how each of these tenets can (or can’t) be applied or adapted to technical writing.


Simplicity–the art of maximizing the amount of work not done–is essential.

When I was a child I read Cheaper by the Dozen by Frank and Ernestine Gilbreth. Their parents were the pioneering industrial engineers and motion study experts Frank Bunker Gilbreth and Lillian Moller Gilbreth. I still remember one of the opening descriptions of their father:

…at home or on the job, Dad was always the efficiency expert. He buttoned his vest from the bottom up, instead of from the top down, because the bottom-to-top process took him only three seconds, while the top-to-bottom too seven. He even used two shaving brushes to lather his face, because he found that by doing so he could cut seventeen seconds off his shaving time. For a while he tried shaving with two razors, but he finally gave that up.

“I can save forty-four seconds,” he grumbled, “but I wasted two minutes this morning putting this bandage on my throat.”

It wasn’t the slashed throat that really bothered him. It was the two minutes.

I re-read the book several times as a child. Probably because my father was an engineer, and I could see Mr. Gilbreth as a slightly more charming version of my father. And I have to say that those repeated readings had an effect on me, instilling me with a bit of a secret desire to be an efficiency expert. When I think about “maximizing the amount of work not done” I always think of Mr. Gilbreth.

This tenet focuses on one of the cornerstones of efficiency – the KISS principle: Keep it Simple, Stupid. This is such a key concept, and yet, so often people forget it. Don’t make extra work for yourself. Find the simplest solution possible to problems. Work smarter, not harder.

Some of the ways that I like to keep things simple include:

  • Using styles and templates. Over the years, I’ve always been surprised at the number of people (including the occasional technical writer) that don’t use styles to format their documents, especially Word documents. The first thing I do when I start working with an authoring tool or a document is inspect the template. Knowing what styles are available saves time when it comes to thinking about how I want to arrange the information that I’m writing. When I’m the one creating the templates (which I’ve done in both FrameMaker and Flare) I first create a basic set of styles, then add to them as needed. When I’m dealing with an overly complex FrameMaker template, I’ll delete the styles that I don’t need. I can always import them back into the document if the need arises.
  • Writing short, simple modular content that is chunked into concept, task, and reference topics. Chunking content into smaller pieces makes it easier to add, remove, and rearrange content as needed. It also reduces the amount of content that users need to scan to find information within a topic.
  • I try to avoid overly complex branching procedures because I find them confusing. I assume that my users would find them confusing too. I try to write short, simple procedures. If a procedure becomes long and involved, try to break it into smaller procedures.
  • Don’t reinvent the wheel. Especially when it comes to something like Style Guides. Pick one of the major style guides (Apple, Chicago, Microsoft, Sun, Xerox) and only document where you differ from it. As a lone writer I don’t have time to write my own in-house style guide. I use the Microsoft Manual of Style (partly because Microsoft is so ubiquitous that it feels familiar to most people, and partly because I can always find a copy on the shelf at my local Barnes and Nobles).
  • Probably the most important way to maximize the amount of work not done is not to include information that the customer doesn’t really need in your documentation. Always keep the customer and their tasks in mind. Sometimes that means that you have to trust your own judgment over that of your developers as to what the user needs to know. Yes, the developer thinks that customers need to know the algorithms and all the other little details about how the software does its thing. But chances are, your customers really don’t need or want that level of detail about how things work. They assume that when they click the button, it will do what it’s supposed to do. You don’t need to be a mechanic to drive a car, and most users don’t need to know the inner workings of software to be able to use it.

Simplicity is essential. Work smarter, not harder.

January 11, 2010

Agile Tenet #9 – Attention to Excellence

Filed under: Uncategorized — heratech @ 8:54 am
Tags: , , ,

Area nine. Ninth in a series of posts examining the Twelve Principles of Agile Software and how each of these tenets can (or can’t) be applied or adapted to technical writing.


Continuous attention to technical excellence and good design enhances agility.

I met Abby Fichtner at the Nashua Scrum Club. Her card included the address of her blog, the Hacker Chick, and since like the elephant’s child I have an insatiable curiosity, when I got home I surfed on over to check out what she writes about. She’s got some great posts over there. I particularly like this one about Craftsmanship where she states that one of the most important lessons of Agile is “the only way to go fast is to go well.”

“How many times have you been significantly slowed down by bad code? Martin asks and we can be sure all programmer hands went up. “Then why did you write it?” he asks. There is laughter because of the truth in his question. We have all been slowed by bad code and yet, we continue to allow bad code to be written on our projects. And why? Because we didn’t have time to write it well?”

“We must not write bad code. Period. This is a fundamental issue of professional behavior.”
– Bob Martin

As I’ve been learning about Agile, there seems to be quite a bit of emphasis on not just delivering software, but delivering better software. When we started our move to Agile at my company, there was a lot of emphasis on testing, with added unit tests, test harnesses, test plans, etc. I’m not sure if we meet all the requirements for test driven development, but we’re probably pretty close. Which means that our next release is going to be of significantly higher quality than our last one. This is good news for our customers, and will hopefully translate into better word of mouth and better sales. I appreciate that the Agile emphasis on speed does not mean that we’re producing sloppy work, but also focusing on quality product.

Abby’s post on Craftsmanship led me to this one where she writes:

“And I just keep thinking back to Clean Code’s preface: if we’re to call ourselves professionals, we have a responsibility to act as such. And maybe that means we really do need a 5th element for our Agile Manifesto: We value Craftsmanship over Crap.

So, how do you adopt this tenet to Agile technical writing? As Agile TWs we need to figure out how to not only write faster, but how to write better. And I’ve been lucky enough to have been exposed to automated tools that can help you be a better writer.

At a previous job we were implementing a pilot program with acrolix acrocheck (which seems to have been replaced by acrolinx IQ) a style and grammar tool that was designed to reduce translation costs. The tool had a number of different features: it checked spelling and grammar, checked a variety of common style rules (as defined in the more popular style guides), and could be programmed to check for in-house terminology and style. You could also use it with Microsoft Word, Adobe FrameMaker, and RoboHelp. Part of our pilot program was figuring which rules we wanted to keep and which we were going to disable. For example, our product had a Users application, so we had to decide if we were going to keep the rule “don’t use the word user in your documentation.”

I’d always thought I was a pretty good writer, but the first time I ran the tool against one of my projects, I was absolutely horrified by how many errors were flagged in my document. It’s a good thing that my attitude towards editing is that is necessary for improvement, or I’d probably have been curled up under my desk. My three most common errors were sentence length, future tense, and passive voice, but there were plenty of other problems. Most of them easily fixed.

I used acrocheck for at least three months as part of our pilot. And one of the things that I noticed was that it was starting to improve my writing, in much the same way that using spell check consistently finally teaches my fingers the correct spellings of words that I initially misspell. I was starting to catch myself using passive voice during my writing process, before I ran the tool against my draft. I also started noticing when my sentences were creeping towards run-on (although, as you may have noticed, it’s still a problem I struggle with!).

The acrolix product is enterprise level, and priced accordingly. Not something that I’m likely to be able to access in my new role as Lone Writer. But if you’re a FrameMaker user, I’ll point you towards the download for SDL Author Assist a FREE grammar and style checking tool. I’ve played with it, and it is worth the upgrade if you’re not yet on FrameMaker 9.

If we’re going to call ourselves professionals, we have a responsibility to act as such. We value craftsmanship over crap.

I love this. This resonates so profoundly with me. This just may be my new motto.


Here is another post on the fifth element for the Agile Manifesto – Craftsmanship over Execution. Read through the comments, they’re great.

January 4, 2010

Agile Tenet #7 – Usable Doc as a Measure of Progress

Filed under: Uncategorized — heratech @ 8:35 pm
Tags: , , , ,

Seven Key Seventh in a series of posts examining the Twelve Principles of Agile Software and how each of these tenets can (or can’t) be applied or adapted to technical writing.


Working software is the primary measure of progress.

Technical writers write documentation rather than software, so this is one of the tenets that needs to be slightly modified to apply to TWs. The question is, how do you define “working documentation” and whether or not the Agile technical writer is making progress?

We don’t want to use page count as a measure of progress. Lengthy docs often lack focus. Mark Twain said, “I didn’t have time to write a short letter, so I wrote a long one instead.” And Cicero, T.S. Eliot, Ernest Hemingway, Samuel Johnson, Blaise Pascal, George Bernard Shaw, and Voltaire have similar quotations about lengthy writing being an indication that they did not have time to do their best. Page counts are not a metric of good writing, in fact, if you localize, a low page count (and lower cost) is the goal.

Tightening up your writing can be as simple as changing “Click on the Save button” to “Click Save” which says essentially the same thing but takes less time to read (and if you’re localizing, saves you three words). But I’ve also seen people take brevity to extremes in an effort to reduce localizations costs. At one point during a cost cutting effort one of our executives found a company that promised to cut our word count by 40%. We sent them samples, but what came back was so spare as to be almost useless. If you’re only focused on word count or page count, you’ve lost sight of your users and meeting their needs.

Since tenet #9 is attention to Excellence, I believe that the measure of progress for a technical writer should be useful documentation. A couple of years ago I encountered the book Developing Quality Technical Information: A Handbook for Writers and Editors. I was so impressed with their definition of quality technical writing that I typed it up and posted it on the wall of my cube. Slightly paraphrased, their criteria are as follows:

Easy to use
Task Orientation Focused on helping users perform tasks related to their jobs.
Accuracy Free of mistakes and errors.
Completeness Includes all the necessary information, and only necessary information.
Easy to understand
Clarity Presents the information so that users understand it the first time.
Concreteness Includes appropriate examples, scenarios, specific language and graphics.
Style Appropriate writing conventions, words, and phrases.
Easy to find
Organization Arranging the parts in a way that makes sense to the user.
Retrievability Presentation that allows users to find information quickly and easily.
Visual Effectiveness Appropriate use of layout, illustrations, color, typography, etc.

I believe that one of the most important things you can do to make software documentation useful is to focus on the user’s task. Several years ago I took a community college course to learn how to use Photoshop. Our instructor chose the Photoshop Visual Quickstart Guide from PeachPit Press as our text. Both the course and the text were feature oriented rather than task oriented. As we worked our way through the many features of Photoshop I remember constantly wondering “But what would I use this for?” At the end of the semester we hadn’t covered what I suspect are the two most common corrections to photographs: removing red-eye and “correcting” skin blemishes. I could probably figure out which features to use, but it would have been helpful if the course and text had focused on common tasks.

Journalists seek to answer the Five Ws: Who? What? When? Where? Why? And How? I believe that useful documentation should seek to answer the same questions.

Useful documentation is the primary measure of progress for a technical writer.

Blog at WordPress.com.