December 18, 2009

Agile Tenet #2 – Welcome Changing Requirements

Filed under: Uncategorized — heratech @ 11:12 am
Tags: ,

Two fingers, V for victory Second 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.


Welcome changing requirements, even late in development. Agile processes harness change for the customer’s competitive advantage.

Early in my TW career a product manager changed a toolbar icon a week before a release. I updated the User’s Guide to reflect the new icon. A day before the release he changed his mind, and reverted back to the original icon, but didn’t tell the doc group. Luckily it was a beta release, so the incorrect docs only impacted a single customer.

While technical writers may not actually welcome change, most of us have had to adapt to the reality that developers often make changes the software and forget to tell us. Getting TWs to welcome change? Well, that may require a major attitude adjustment for some of us, as whingeing about how we get no respect is as much a part our perception of our jobs as it was part of Rodney Dangerfield’s comic persona. Many of us spend our days trying to earn that respect by subtly reminding our coworkers that we provide customer value too.

I think that part of the value of a technical writer is often found in the types of questions that they ask about the products that they document. When I was first investigating technical writing as a career change I attended an information session for a TW certificate course. The speaker was a graduate of the program whose previous career had been as a journalist. I remember that he said that his new career was much like his old career; he still spent his days interviewing people, then going back to his desk and writing. Ever since then I’ve looked at my work as a form of investigative reporting.

For example, if the new feature is to allow the user to create or change a password, I might ask the following questions:

  • Can the password match the user name?
  • Are there any length requirements or restrictions for the password?
  • Is the password case-sensitive?
  • Are there any requirements for the first character in the password?
  • What special characters are allowed in the password?
  • Does the password expire?
  • Can you reuse passwords or partial passwords?

When would it be more helpful to the project to have the technical writer ask these questions? Would you rather have them ask the developer after the code is complete, or ask the customer or product owner during the Sprint planning process, while you’re writing the acceptance criteria for the User Stories?

Agile processes harness change for the customer’s competitive advantage.

So not only do TWs need to welcome change, we need to figure out how to harness it for our customers. I think one of the ways that we can do this is to keep up with the changes in technology and how information is shared in the Internet age. There are many new options for delivering content to our users. Yesterday my former manager sent me a link to the documentation Wiki that he’s working on. And there has been a brief discussion on the TECHWR-L mailing list recently about using WordPress as a documentation platform. I’m still waiting for my copy of Anne Gentle’s Conversation and Community: The Social Web for Documentation to arrive. I’m looking forward to finding more good tips for harnessing Web 2.0 for my customers in her book.

This tenet ties into one of the core TW goals, to understand users and their tasks so that we can write useful documentation. I think the trick for the Agile team is finding the right balance between understanding the user’s requirements and reducing project documentation so that you can get down to the business of creating the product. Technical writers, with our user focus, can help our teams remember that the goal is to meet our users’ needs, not just deliver working software.


December 16, 2009

Agile Tenet #1 – Satisfy the Customer

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

Business route 1 The Agile Manifesto includes Twelve Principles of Agile Software. Over the next dozen entries I’ll look at how each of these tenets can (or can’t) be applied or adapted to technical writing. And then, as a wrap up, I’ll propose my own list of Agile Principles for technical writers.


Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.

Companies deliver two things to customers, software and documentation that explains how best to use it. Developers deliver software. Technical writers deliver user documentation. And technical writers, like developers, aim to “satisfy the customer” when we create our deliverables.

It’s hard to satisfy your customers if you don’t know who they are, so one of the first things good technical writers do is perform an audience analysis. What industries do your users represent? Who are the people using your product? Are they students, office workers, managers, the general public? What level of computer experience do they have? Are they novices, experienced users, system administrators? What environments are they working in? Are they outdoors, in an office, in a clean room? Sometimes this information is easy to come by, and other times we have to take our best guess.

“Early and continuous delivery” of the most up-to-date information is a constant challenge for TWs. In the not so distant past, when TWs were mostly producing hard copy manuals, they were restricted by the lead time required for printing. Often the documentation was out-of-date by the time the product was released. Now that most of us are delivering our documentation as PDFs or online Help, we can release updated deliverables much more quickly. However, TWs may still be restricted to releasing documentation once a quarter or less. At a previous company we localized into a dozen languages, and often were not allowed to release updates if there wasn’t the budget to translate the content. The reason for this was never fully explained to me, but it was intensely frustrating to have corrections and new content and not be allowed to release them to our customers. Currently, I’m working as a lone writer for a company that doesn’t yet localize. So I can update the documentation as often as I like. Since we have a patch release cycle of 6-8 weeks, I update the docs whenever we release a patch.

Developers deliver “valuable software”, but what makes documentation valuable? I think that Developing Quality Technical Information sums it up quite nicely, when they say that quality technical information is
• Easy to use
• Easy to understand
• Easy to find

Valuable documentation helps customers do their jobs. Customers don’t search the documentation for headings like “Using the Widget Dialog Box.” They look for “How to Order Widgets” because they don’t know which feature they need to use, but they do know the task that they need to perform. At every technical writing job that I’ve had in my career, I’ve spent my time turning feature based documentation into task based documentation. I focus on breaking the documentation down into small chunks, organizing it effectively with meaningful headings, and indexing it as thoroughly as possible. And whenever I can, I also include best practices for how to use the software and tips for how to be more efficient.

The technical writer’s highest priority is to satisfy the customer by providing useful documentation.

November 21, 2009

Approaching Agile

Filed under: Uncategorized — heratech @ 8:31 am
Tags: , , , , , , ,
Little girl peeking through fence

Sneaking up on it

I think I was destined to become an Agile technical writer.  In the summer of 2008 I was working for a small software company that produced two different products.  After finishing up a stretch of concentrating on the documentation for product A, I checked in with the product B developers in New Zealand.  I discovered that they’d decided to adopt Agile development without telling me. 

I responded the way I always do when faced with a new idea.  I did some research.

I started out by checked the Techwr-l archives for threads that mentioned Agile.  I’ve been a member of Techwr-l since 2005, and since I use G-mail to manage my list subscriptions, it was fairly easy to find the few discussions of Agile from the past couple of years.  Unfortunately, what little I found didn’t sound too encouraging from a tech writer’s point of view.

I also looked through my collection of back issues of the Intercom, the journal of the Society for Technical Communications.  I found two articles about Agile documentation:

  • Adapting to SCRUM: Challenges and Strategies (July/August 2007)
  • Extreme Documentation (February 2003)

Wikipedia and Google turned up plenty of articles, and also led me to the Agile Manifesto and Scott Ambler’s Web Site.   I had to do quite a bit of reading before I finally realized that when Agile proponents were writing things like “Documentation should be just barely good enough.” and “The benefit of having documentation must be greater than the cost of creating and maintaining it.” They were talking about project documentation (design documents, functional specs, etc), not product documentation like User Guides and Help. And with the exception of the STC articles, none of the resources I was reading were talking about what a technical writer would produce, or how they fit into Agile (other than being part of the Scrum team).

I had just started reading Agile Software Development with Scrum when a friend forwarded a job opening to me.  The job description sounded like a very good fit with my skills and interests.  The company was looking for someone with experience working in an Agile software development environment.

By this point I’d learned enough about Agile to know that the way we were implementing it at my company (developers in two different cities, the tech writer and project manager on a completely different continent) was not going to be conducive to my success as an Agile Technical Writer.   And I was intrigued by Agile. I now knew enough to be able to “talk the talk” during my interviews.  During my interview I quizzed the VP of Engineering.  They were still using the Waterfall Model, but were planning to switch to Agile development at the beginning of 2009.  

I liked the idea of getting in at the beginning and being able to shape the way the technical writer fit into the Agile team.   They made me an offer, I accepted, and I started work there in October 2008.

Fast forward to May 2009 and the end of Sprint 4.  The last day of the sprint our company had a layoff, and I was one of the casualties.  Six weeks later they called me back to work part time (two days a week).  So while I’m still working in an Agile environment, I’m no longer embedded with the team working to document the current sprint.  Hopefully that will change as the economy starts to recover.

« Previous Page

Create a free website or blog at WordPress.com.