Writing End-User Documentation in an Agile Development Environment

This article was original published in the June 2007 issue of the CIDM Best Practices Newsletter. It is re-published in its entirety with the permission of the Center for Information Development Management.

In this article, we examine an increasingly popular development methodology from the Extreme Programming family—Agile development—and how technical writers can operate successfully in this methodology. We answer the first questions technical writers might ask when assigned to an Agile team:

• What is Agile development?
• How does Agile development affect my role on the team?
• What are the best methods for succeeding as a team member with this software-development methodology?

The experiences we discuss come from using Agile and a related methodology, Scrum, in creating enterprise software, like database administration tools, rather than Internet applications like Yahoo! Photos. This distinction is necessary because of the vast differences in the length of release cycles; enterprise software teams deliver in three to nine month cycles, while some Internet software teams deliver in cycles as short as two weeks. These differences mean that the implementation of Agile development varies greatly. Now, let’s look at some guiding principles of Agile development.

Agile Development Defined

The main principle of Agile development is to develop robust software rapidly with minimal expense and investment in detailed, up-front design. “Robust” and “rapid” are manifested in the use of iterations, or short development cycles (usually 2–3 weeks), in which a particular piece of the software is developed, tested, and documented. A development cycle built on iterations allows for rapid and continuous delivery, and it provides agility and flexibility that are missing in more traditional development methodologies. Problems are quickly discovered, and teams can either immediately correct a problem or eliminate an affected feature altogether without wasting design work that would have occurred in traditional methodologies, such as waterfall.

The Agile methodology is part of a large family of development processes and has no single, prescribed method. Many companies create their own Agile methods while using some of the original ideas and principles defined in the Agile Manifesto (http://www.agilemanifesto.org/).

A basic tenet of Agile methodologies is “Working software over comprehensive documentation,” meaning that internal design and specification documents are minimal or non-existent. Many technical writers struggle to be fully functional in such a development environment. Writers have traditionally relied on design documents to get a “big picture” of the product—what it does and how it works. The amount of internal documentation varies widely among Agile teams. Some teams do not even produce a list of product features, relying instead on their Agile planning software to act as a repository of the list of stories and tasks to be accomplished in each iteration.

Another tenet of Agile, “Individuals and interactions over processes and tools,” can make writers feel marginalized when determining how best to function in the team. Fortunately, the best Agile teams understand the value of end-user documentation or can be shown that an integral part of creating successful, working software is excellent documentation written in a tightly collaborative environment. In such an environment, the technical writer can adapt and even shine.

The Language of Agile Development

Often the most intimidating part of learning anything new is grappling with a new vocabulary, and Agile is no exception. Following are some basic terms that are used frequently in Agile teams:

• Iteration: A period of time during which the software is programmed and at the end of which the quality assurance (QA) testers verify that the software is working as expected.
• Stand-up: A daily meeting in which the progress of the software development is communicated.
• Story: The business need that defines what the software will do for the user. Stories are usually sized so that a single iteration is enough time for development, and they are usually written as “role can do task” (for example, “An Administrator can add a new User”).
• Task: Defines all of the subtasks for a single story. For example, for the story “An Administrator can add a new User,” one of the tasks might be “Connect the new component to an existing security component.”
• Backlog: A repository for stories that are targeted for release during an iteration.

How Does Agile Affect Your Role and Processes?

As part of an Agile team, you are expected to tell the team what you will deliver at the end of an iteration. Working in iterations has a definite affect on the scope, content, and presentation of your deliverables. You must be prepared to communicate your status daily because many Agile teams track progress on all stories and tasks daily.

Some techniques and certain deliverables are well suited for documenting products that are developed in an Agile environment:

• using a topic-oriented approach such as the Darwin Information Typing Architecture (DITA) or Information Mapping^TM
• leveraging user stories to produce task-oriented documentation
• applying minimalist principles
• participating as an active team member

Topic-oriented writing

Most writers are familiar with topic-oriented writing: authoring concise, self-contained units of information about a specific topic. Topic-oriented writing is a defining aspect of Information Mapping and DITA. In Information Mapping, complex information is broken down into basic components, and then the “chunks” of information are structured in a reader-friendly way. In DITA, information is categorized into concept, task, and reference topics. Such categorization makes sense in an Agile environment, in which “the right documentation at the right time” is the main goal for all documentation, end-user and internal.

In addition, DITA maps offer just-in-time assembly and output generation of documentation, which provides a huge advantage when creating Agile documentation. In an Agile environment, changes that make the software better, even at the end of an iteration, are welcomed and encouraged. But if a new function is eliminated from an iteration after you have already documented it, you just remove those topics from the DITA map for that iteration’s build. Keep those topics for the next time that feature is worked into a user story, and you become the hero when you link those topics in a new DITA map and generate output.

Translating User Stories into Task-Oriented Topics

In an Agile environment, development is driven by user stories, which define the tasks that end-users want to accomplish with the software. User stories must be customer-focused, succinct, and testable, and writers can leverage them to create user-focused, task-oriented documentation.

Task-oriented writing not only complements development’s use of user stories, but it is an absolute necessity given short iteration cycles and an often limited number of writing resources. The requirement to create installation and configuration information and solid procedural information (probably in an online Help system) often leaves little time in any release cycle to create much conceptual or best practices information. Such information can, however, be produced following a particular release cycle. The focus on tasks within a cycle, however, helps writers achieve minimalism, another technique particularly well-suited to documenting in an Agile environment.

Just-In-Time Documentation Also Means Just Enough

Minimalism in technical documentation has been advocated since IBM’s John Carroll wrote The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill in 1990. Minimalist principles are especially relevant when you adapt Agile methods to produce working documentation that complements working software at the end of short iterations. For example, you should avoid wordy overviews that are not task-based, and you should not even document obvious procedures such as how to cut and paste text or print reports.

The Importance of Team Spirit

Being an active member of the Agile team is crucial to a writer’s success. The lack of internal documentation makes full participation in the team an absolute necessity. Your awareness of hallway conversations and impromptu white board drawings about changes to the GUI, for example, could mean the difference between completing your stories or tasks within the specified iteration or not. The need for such camaraderie obviously must be understood and embraced by the developers and testers on your team.

Ideas for Best Practices

Having survived and thrived during releases using Agile methods, we have a few ideas for best practices, as well as pitfalls to avoid:

• You will be most successful if you are dedicated to a single Agile team, not a resource shared by several Agile teams. This focus enables you to attend all meetings, like the daily stand-up, where you can gather information and overcome roadblocks.
• Encourage and embrace the face-to-face communication that is a driving force in Agile.
• Locate your workspace near your developer and QA teammates if possible. If you cannot work physically near your Agile team, find ways to communicate as personally as possible in real-time, such as using Instant Messaging or web cameras with video conferencing.
• Agree with your development team on two key points:1. should the documentation tasks be included in the development team’s story or housed under a separate, documentation-specific story?
  2. how many iterations can the end-user documentation lag behind the development team’s completion of a feature?
• Write user stories for documentation that parallel the user stories that are being used to build product features. An example user story for documentation might be “A DBA can read online Help to learn how to manage licenses.” An alternative is to create documentation-specific tasks that are included under the development team’s user stories. For example, the development team might have already created a story called “A DBA can manage licenses”; as the writer, you can simply add a documentation task to the story. Another idea is to house all documentation stories and tasks under a parallel project, so that you can easily estimate documentation’s velocity.
• You must have access to the same planning tool that the Agile development team is using. This tool may be software based, such as Rally or XPlanner, or it may be index cards on a cork board. The ability to create entries gives the documentation tasks equal visibility and footing with development and QA tasks related to each user story. In some environments, the planning tool is the only place to see a comprehensive list of the product’s planned functionality, as represented by the stories.
• Request that all user stories be stored and accurately maintained in a single place, which will most likely be the Agile planning software. Ideally, the product manager or development team creates a product feature list or some document that states all of the product functionality.
• Write a minimal documentation plan so that you can focus on story planning and end-user deliverables. The documentation plan could list the key contacts, release theme, top stories, dates, and your expectations and assumptions.
• For each user story, ask the QA team to create an equivalent task for reviewing the online Help or other documentation.
• Request a “hardening” iteration in which you can complete final tasks for your deliverables—for example, check index entries on final assemblies or determine the optimal organization for a table of contents. Final user stories for documentation might end up in a “hardening iteration” that includes technical reviews.
• Use the backlog to house documentation tasks. First, pull high-priority, low risk items from the backlog into an iteration, and then return to the backlog for lower-priority or higher-risk items in another iteration.
• Keep your documentation task-oriented, in line with the user stories that are promised with each iteration. If you want to take task orientation to the next logical level, write your end-user documentation in a topic-oriented way with tasks having supporting concepts and reference topics, much like the DITA prescription.

Conclusion

Just as programmers employ Agile techniques to improve their deliverables, technical writers can employ complementary writing techniques to become an integral part of delivering useful software. End-user deliverables that are task-oriented and help the user perform at an expert level become a necessary and valued part of the success of a product developed using Agile methods.

Bibliography

Beck, et al., Manifesto for Agile Software Development http://www.agilemanifesto.org

Broderick, Stacia and Melody Locke. “A Tale of Two Writing Teams.” agile, pp. 295-304, AGILE 2006 (AGILE’06), 2006.

Cohn, Mike. Agile Estimating and Planning Prentice Hall PTR, 2005

About the Authors

Tana Berry
Senior Technical Writer
Database-Brothers, Inc.
tana.berry@database-brothers.com
Tana works as the only technical writer at Database-Brothers, a small company with a focus on database auditing and performance products. She has enjoyed working as a technical writer for more than twelve years and has been an active team member on an Agile team for a year. Tana loves Agile because it forces the writer to produce lean, task-oriented documentation with the end-user always kept as the focus.

Anne Gentle
Senior Technical Writer
BMC Software
anne_gentle@bmc.com
http://talk.bmc.com/blogs/anne-gentle
Anne Gentle works at BMC Software where she writes technical deliverables ranging from user manuals to online help to white papers. BMC has many product lines adopting Agile development methods and the product Anne now writes for, Configuration Management, has recently become Agile. Known to enthusiastically discuss communication topics ranging from blogging to wikis to XML-based information models like DITA, she sees DITA as an excellent gateway to more Agile documentation.

[digg=http://digg.com/software/Writing_End_User_Documentation_in_an_Agile_Development_Environment]

Subscribe to the comments for this post

Alterpoint blog gives kudos to our Routes to Value approach to BSM and ITIL

Alterpoint is located in Austin (where I’m located) and makes network management software that is integrated with our BMC Remedy Action Request System and BMC now resells their product, DeviceAuthority. With just a couple of “follow this idea” clicks, as often happens when I read blogs, I found this blog entry, ” Break it Down: Making Strides with ITIL and Best Practices.” In it they give props to BMC for creating the BSM Routes to Value that make the sometimes daunting task of implementing best practices for IT manageable — by breaking it down into parts that make sense. My favorite lines from this post are these, because it mirrors my own observations lately.

One of the basic points is that these transformational projects have too much at stake to be threatened by internal pride or lack of good internal assessment. To realign around ITIL or other best practices, you often need to adjust, enhance or expel some process and cultural factors that are baked into your operation before you even start talking about technology.

I’ve got a white paper in progress where I offer observations of methods for implementing ITIL best practices, starting with the infrastructure tools you already have in place, and in it I discuss getting started with small projects that can later add up to more. You hear corporate culture stories when you start to talk about ITIL projects, and Gary Holmes has some great observations in his comment on Throw out ITIL, but keep the CMDB?. I look forward to hearing more corporate culture and organizational communication stories as I continue to learn about this IT Infrastructure Library myself.

Subscribe to the comments for this post

Best practices in tech comm for fit in the organization

This post is another part in a series about best practices in technical publications for software companies. Other posts include “ Questions for best practices in technical publications” and “Best practices for document management systems.”

A couple of the best practices listed in the article, “Tech writers as sales reps?” that we referred to for our Austin STC Meeting in October 2005 are related to where a tech pubs department best fits in a company, and what staffing levels are best suited for success. Specifically, the three best practices that the article mentions are:

#4: Have a reasonable ratio of writers to developers.
#5: Place technical writers somewhere sensible in your org chart.

#7: Encourage technical writers to meet customers.
#8: Use customer advisory boards to get feedback on documentation.

I then asked each manager to answer the questions below from their perspective. Here are summaries of the answers and wisdom given.

Q: The author of this article places technical writers in customer support. Is that the right placement for your company and team?

A: All three managers have teams that are located not in customer support, but rather are located in research and development, although the writers at smallest company sit near their technical consultants. So, their interpretation for the article was that perhaps customer support played a very strong role in that particular company, so from a power standpoint, it was a good placement in his case. One manager noted that regardless of where you are in the org chart, you can be physically located near development in order to build rapport and get information that you need.

All the managers realize that having the documentation team close to a group that drives the company can be a positive position. They noted that this positioning can also be a double-edged sword, because a shift in power can place a layoff target on the documentation team.

Q: Do you agree with the author’s 8:1 developer:writer approach? How do you estimate your ratios? What’s the right ratio? How have you used this ratio when asking for resources?

As the article notes that even 20 or 30 developers to each writer can exist, the managers stated that these figures can vary. At the smallest company, a 5 to 1 ratio is in effect, which works very well. The range was anywhere from 5:1 to 10:1, but the managers agreed that the age and maturity of the product being documented should really affect this number. Newer products should have fewer developers per writer. This idea sounded good to me, that the ratio really depends on the new material needed versus maintenance of established documentation.

Subscribe to the comments for this post

Questioning technical publications best practices

Here are the questions I asked of our panelists at our October STC meeting in Austin that further investigated and challenged the best practices listed in the “Tech writers as sales reps?” article on which we focused.

Over the next few weeks, I’m going to group some of the responses into different categories of “best practice” and enter a post for each. I’m just writing what I’ve taken away from the session.

The first has to do with best practices for Document Management Systems based on a question from a reader, which I’ve already posted. The second I’ll title “Best practices for connecting tech pubs to the rest of the business.” The third part will discuss best practices for staffing and suggestions for resourcing, and finally I’ll discuss best practices for structured authoring, a topic on which I think the original article missed the point. There’s a difference between single-sourcing and structured authoring, and the author doesn’t fully realize the missed potential by sticking mostly with single-sourcing.

First, the list of best practices with the questions I posed to our panel.

#2: Understand the value of good documentation.
How do you prove Return On Investment (ROI) for tech pubs at your company? Is the author’s “use customer support to prove ROI” argument a valid one in your experience?

#3: Use documentation to gain an edge.
Does this happen in reality? Do most executives share this view? How have you tried to tell your executives that your documents help you gain an edge?

#4: Have a reasonable ratio of writers to developers.
Do you agree with the author’s 8 developers for each writer approach? How do you estimate your ratios? What’s the right ratio? How have you used this ratio when asking for resources?

#5: Place technical writers somewhere sensible in your org chart.
The author places technical writers in customer support, is that the right placement to you?

#7: Encourage technical writers to meet customers. and #8: Use customer advisory boards to get feedback on documentation.
Customer interaction – discuss constraints on really making this happen. How have you made it happen?

#13: Try out conditional text.
How do you ensure it is used wisely? How do you set up standards? Is this a tool-based decision?

#14: Explore single sourcing.
Do you agree that single-sourcing is the answer? Is he using the old definition of single sourcing, where you don’t really repurpose content? Is the new idea of structured authoring where exploration should occur instead?

#9: Make the right tradeoffs.
How do you ensure that writers focus on content rather than formatting? How can an editing team ensure that the right tradeoffs are chosen? What tradeoffs are there between information quality and quantity?

#10: Pick the right medium for each deliverable. and #11: Provide print for those who need it.
The question is, how can you ignore the costs of 3,000 pages of printed documentation? How much print do each of your departments provide?

Subscribe to the comments for this post

Best practices for document management systems

I recently received a question about best practices for electronic document management systems using Word 2003. While I use Word 2003, I have only used it in combination with Sharepoint as a document management system, and the docs I write in Word are usually short, internal documents, not external technical manuals. Coincidentally, I’ve heard that IT departments are using document management systems in concert with their CMDB. Text-based documents, drawings, architecture designs, all these documents are important to an IT department and any business organization. It makes sense that the CMDB would be related to a document management system, although I won’t get into any discussion about whether each document is a Configuration Item (CI) or not.
My experience with document management is Documentum with FrameMaker, and we don’t currently do much co-authoring with people in the rest of the company. So I’ll admit first off, this request for information is outside my personal knowledge. But, I do like a good research question and I gathered together some reading items.

Here’s a summary of what’s found in this article about putting together a document management system using Microsoft tools. Your environment may vary widely from an accounting-type environment, though, but I thought these were decent overarching goals for managing documents, and I expanded on a few of them based on my experience with document management systems in general.

1. Determine what documents get the “document management treatment.” Create limits on what is stored and maintained in your system so that you know what’s in there and what’s not, and you also limit maintenance and a bulging file system. Will you scan and store images of paper copies?
2. Classify or group your documents together. Some EDMSes do this for you using document type, but you might also want other criteria for easy search and retrieval later. This approach also allows you to assign more than one classification to a document.
3. Store the files efficiently to make retrieval easy. Your EDMS might do this on its own with little input from you.
4. Retrieve as needed, using versioning if desired, which leads to the next step. Realize that indexing and keyword searching are crucial tasks for retrieval. Be sure to train users to properly tag documents for fast and efficient retrieval. You may have to create a taxonomy using standard terms for the system.
5. Managing and tracking documents allows for the type of collaboration where one person can check out a document to make revisions. Other collaborative activities might include activities such as participating in active discussion groups, tracking issues associated with customer engagements, maintaining common contact information for subject matter experts on a particular document, and even assigning tasks related to a particular document. Tracking and versioning also allows for storage and retrieval of documents from a point in time which may be helpful historically.

For research like this question, one place I like to do searches is answer.google.com. There was one relevant Answer for someone who was looking for an analysis of document management software. It’s long but comprehensive. I realize you might be well past the evaluation stage for a DMS, but you might get a look at what features are offered. You can also use blogsearch.google.com to search only for blog entries on a given topic, although that particular search method did not offer much on this particular topic.

Going beyond Google, I did a search using www.bloglines.com to search for blogs about “document management systems,” and the best I’ve found so far is www.docuvantage.com/blog. Another site that offers a wide range of case studies and white papers is The Gilbane Report at http://www.gilbane.com/.

There are also lessons learned from the doc management trenches at Hewlett-Packard. It appears the author is Susan Charles, an Information Research Analyst at Hewlett-Packard. She describes the implementation of an internal document management project at HP. She discusses the challenges of the project, and what she sees as the lessons learned.

In addition, here’s a case study from a university setting. I haven’t read through it completely but it might offer some advice.

As with many best practices in technology, you want to analyze first and implement second. Spending more of your time in the up front planning and definitions will pay off when you go to populate your system with documents.

Anyone else have some advice to offer? Feel free to post a comment, or use the trackback URL to write about it in your own blog and refer to this entry.

Subscribe to the comments for this post