HeraTech

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.

Advertisements

6 Comments »

  1. There was a follow up to the “craftsmanship over crap” comment that Bob made. The Agile manifesto says that whilst the items on the left and right are important, we value the items on the left more. In the case of crap, we shouldn’t value that all…

    Comment by Craig Smith — January 11, 2010 @ 7:17 pm | Reply

    • True, very true.

      But in the case of documentation, some companies seem to take the stand that “any documentation is better than none” and thus end up shipping crap. This is an attitude that I try to fight. Quality doc is always better than just shipping “something.”

      Comment by heratech — January 11, 2010 @ 11:39 pm | Reply

  2. So excited to discover your blog thanks to Twitter. We need more tech writers on agile projects! I’m a big fan of Abby’s also.

    Comment by Lisa Crispin — January 11, 2010 @ 7:53 pm | Reply

    • Welcome Lisa. Are you an Agile TW, developer, or tester?

      (Whoops, I should click through my links before I reply, shouldn’t I?)

      Comment by heratech — January 11, 2010 @ 11:40 pm | Reply

  3. […] Agile Tenet #9 – Attention to Excellence (Julie Stickler) […]

    Pingback by Dew Drop – January 12, 2009 | Alvin Ashcraft's Morning Dew — January 12, 2010 @ 10:02 am | Reply

  4. Hi, Julie – wow, thank you so much for mentioning me in this awesome post! How funny, I just came across your business card last week sitting on my bookshelf and wondered how you were doing.

    I think programming is similar to writing in so many ways. I always say, we wouldn’t just write a first draft of an article and then send it to the publisher, why do we do that with our code?? 🙂 Good to see that writing is getting similar tools to coding to help us check ourselves!

    I hope to see you at future ScrumClubs. Our talk before got me really thinking about where tech writing fits in agile, so cool that you’re out there making the question more visible!

    Comment by abby, the hacker chick blog — January 30, 2010 @ 4:28 pm | Reply


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Create a free website or blog at WordPress.com.

%d bloggers like this: