Tag Archives: agile

STC2008 – Wrap up STC Summit trip report

I had a great time in Philly for the STC Summit, and here are some of my takeaways.

Collaboration is a huge part of our jobs, whether it’s finding others in your company to collaborate with as the two technical writers from Sun have done while creating screencasts with a “rock start developer” or the collaboration they do with users as they became community members and sometimes moderators, collaborating with the developers who use the product they are documenting. Collaboration means that you’re willing to learn another’s language, whether it’s another country’s language or learning the vocabulary of Scrum. Collaboration and structure can work together, such as the power of collaboration on a wiki, if you can find a common language (or currency), such as DITA.

My manager’s takeaway had a lot to do with Agile, and I see Agile as the ultimate collaboration mechanism for writers to integrate themselves not only with the development team, but also the business analysts who take the product to early beta with customers, and in that way, technical writers can get even closer to customers. I wrote an article for the CIDM Newsletter last year with ideas for thriving and surviving an Agile environment, so the topic is near and dear to me, but since I’ve not had to be part of an Agile dev team since leaving BMC, I chose not to focus on those sessions. I enjoyed the writeup by Richard Hamilton describing Mike Wethington’s Agile talk with each slide as a sprint followed by discussion. Agilists are living’ it, folks.

Conversation was another theme I chose to follow, due to my interest in writing a book on the topic of designing conversation and community into documentation. I was fascinated with the Asynchronous Conversation talk that Ginny Redish gave and she offered so many examples of how even the writing you do can be re-written to be more conversational – not just having style guides that allow for informal style and voice, but also removing passive voice, ensuring you know who’s the actor and what is being acted upon, and so forth. Confirmed my instinct that conversation, collaboration, and content are close cousins if we can figure out how to best combine them all.

Community is a huge part of what I have been paying attention to, and the sessions I attended and the attendees I spoke with gave me more insights into tapping the power of communities. I also found it fascinating that speakers at two different talks (Sun and IBM) mentioned finding “celebrities” when building wikis or screencasts, because communities wanted to watch the “rock star” work while they built the wiki or listen (and speak back) to their heroes while the heroes did their jobs as a subject matter expert.

Career plans and the business aspects of convincing others where your worth lives as a technical communicator were constantly brought up in the question part of the sessions. How did you prove that a wiki and screencast were the right way to take the content, when the online help had to be further minimized to do so? In our collaboration panel we were asked, what if you’re in an environment where obviously the wrong tool was chosen for a technical publications group, yet the writer felt powerless to prove the absences of ROI (Return On Investment) for that particular business and tool decision? I listened to these questions with a heightened sense of awareness of my own weakness in this area. While I can implement great ideas, proving that the idea needs to be implemented in the first place means understanding how to convince management of the value.

So, putting your manager hat on, where’s the value in conferences?

I read Tom Johnson’s notes from the conference with interest, and while I haven’t asked him this specifically, I think he and I share some struggles of attending and presenting at these conferences – we’re often invited, sometimes compensated, but it’s not our “job” to attend and present, as it is for the consultants of the world. I’m a reluctant traveler, though eager presenter. How can I justify the time and expense? Believe me, I have to justify to myself and my family before I even purchase a plane ticket, step foot on an airport shuttle, or draft up a Powerpoint slide deck.

My overall plan is that I try to go to the STC annual conference about every other year, when I’m not pregnant, ha ha. Before Philadelphia, the most recent annual STC conference I attended (and presented at) was three years ago (is that right?) in Baltimore, Maryland, and for some reason that one did not seem as “big” as this one. With probably over 1,300 attendees, Philly felt large to me, even though SXSW Interactive was probably the largest attendance I’d seen at a conference recently with over 9,000 people there just for Interactive.

Personally, I’m finding the value in interactions

I hope she doesn’t mind if I mention this, but I owe a huge thank you to Char James-Tanney who listened to my internal struggle via email while I hemmed and hawed over whether to attend the STC Summit at all this year. Working parents know that the burden is placed on the spouse at home with the kids, and my husband rocks all over the planet when they have “boy’s club” days with me. But. Family life lately has involved some funerals, minor medical issues, and just plain life, which always complicates travel plans. And then there’s things like how much really young kids grow and change in a matter of days. For example, my 18-month-old son who couldn’t reach doorknobs before I left for a conference, could open doors when I returned. And that was after a four-day trip! 🙂

Yet I have always found that the people I talk to and the relationships I forge in face-to-face meetings show enough value to make the travel hassle and lost kid growing time worthwhile. Heh, I wonder what my sons will say when they read that in ten years? I also believe that it can be good to be away from family just so you appreciate what you have when you return. I know I do.

Sarah O’Keefe and Scott Abel have been wonderful for me to simply email or call when I’m looking for mentors in this strange grey area between (not) consulting and offering expertise on the web. I didn’t necessarily have to attend a conference for these generous people to let me reach out, and it’s plain fun to get to know them.

Balancing act, of course

What I’m trying to do lately is find a balance and see what I can do to share my knowledge remotely and do a lot of blogging, emailing, e-networking, and local networking. Austin’s a completely awesome place to work and live and meet others who are forward-thinking, business-minded technical writers and managers. Heck, I can meet them for lunch, and not have to travel further than a few miles to do so. I’m also finding ways to collaborate on STC services with STCers around the world. I’d love to hear others thoughts on the balancing act and whether it changes as your life at home changes. From what I’ve observed, the long view is the most varied view when it comes to participation in STC and conferences.

What I mean by that statement is this: some of the greatest, most active STCers I’ve been fortunate to know, hit their stride when their kids went to college. I plan to be around STC for the next 20 years at least, and I’m already nearly 15 years in. STC is the kind of organization that can support that long view if my observations of others are any indicator.


Building a DITA-Wiki Hybrid

Article PDF for Building a DITA-Wiki hybrid

The April 2008 issue of the STC Intercom magazine is dedicated to DITA (Darwin Information Typing Architecture).

I’m pleased that the Building a DITA-Wiki Hybrid article that I co-authored with Lisa Dyer and Michael Priestly is available online for free to anyone, STC member or non-member. The article discusses these three ideas for merging DITA and wiki technologies:

  • DITA Storm, an online DITA editor with an edit button on each page. While it’s not quite a DITA wiki, it seems like it could become one with some RSS notification and comment or discussion ability on each page.
  • Wikislices are a cross-section of a wiki such as Wikipedia, currently created with school curriculum in mind. Michael Priestly and I are working on a team to find ways to use DITA maps to manage and build wikislices.
  • Lisa Dyer has implemented DITA as a single-source with wiki as output for a documentation site housed behind a Lombardi customer support login.

I’d love to hear your comments on the article here and any other ideas you have seen for a DITA-wiki hybrid.

April 16 Central Texas DITA User Group meeting

From http://dita.xml.org/book/central-texas-dita-user-group

Using DITA Content for Learning Content Development

John Hunt, of IBM, will give a presentation regarding the use of DITA for learning content. He’s been working on a new Learning and Training Content specialization that will be part of OASIS DITA 1.2 release. If you’d like to do a little pre-work, check out this article about using XML (such as DITA) for learning content: http://www.ibm.com/developerworks/xml/library/x-dita9a/

A map domain for a learning object


John Hunt, DITA Learning and Training Content Specialization SC chair. John is also DITA Architect and Learning Design Strategist in the Lotus Information Development Center at IBM.

I’m also looking forward to Mike Wethington’s presentation to the DITA user group for the May 21 meeting, where he will talk about Agile development and its affect on technical communications. Mike’s the manager of technical communications at Troux Technologies here in Austin.

How to be an Agile Technical Writer with a cool acronym like XTW

One reason why I like the show Dirty Jobs so much is because Mike Rowe, the host, is so respectful and honest about the work that people do each day. Dirty Jobs offers such a great viewpoint on work that is done each and every day. I recently discovered that Sarah Maddox, a technical writer at Atlassian (makers of the Confluence wiki engine), has written two great posts about being an Agile technical writer, or an eXtreme Technical Writer (XTW). These posts on Agile Technical Writing offer wonderful windows into the work that technical writers are doing around the world. Plus, they offer some down-to-earth how-tos that make sense to apply in a modern technical writing career. If you’re thinking about technical writing as a career, check out these two posts for your research, because I believe that agility is one of the best skills you can bring to this career path when I consider the direction it is heading.

  • Plus don’t miss the great photo art mashup in the agile technical writer part II, another excellent post that really describes what it’s like to write in the Agile development environment.

Here are some highlights from each that I could identify with:

  • Responding to IMs from all over. Carrying on multiple conversations intelligently is a gift.
  • Concerns about information overload – it’s daunting, but do-able. (Okay, funny side note – My typo for overload was “overlord.” Yipes. That can happen too.) My advice is to ride the serendipitous river of information. Sounds like hippy advice but somehow it works.
  • What a wonderful viewpoint of how the daily life of a technical writer has changed so greatly over the years. I listened to Linda Oestriech’s podcast about the Direction the STC is Heading at Tech Writer Voices and one great quote from her was, “We’re not the technical writer from the 70s.” I’d say we’re not even the technical writer from the 90s.
  • Love the Swaparoo idea – similar to pair programming, but call it a swaparoo when you want to trade tasks with another writer to get cross-product knowledge.
  • Respond to customers from the varied means of communication that is offered to you in this awesome world of documentation. And if it doesn’t have to do with the doc, don’t meddle, pass it along to the support team.

Thanks Sarah, for sharing such a great “day in the life” slice for technical writers.

Authoring and delivery tools for the Agile Technical Writer?

I’ve had a question via email recently, asking something like, “What is the ideal toolkit for writing in an Agile environment?” Or, “What would you choose if you had to write in an Agile environment in order to be most effective as a technical writer?”

It’s tempting to actually try to answer that question with a straightforward response of one tool – but of course the answer is not that easy. The product and audience and company that you’re writing for all dictate the documentation deliverable with far more weight than the “manufacturing” process that is used to build the product. Sarah’s posts don’t directly mention their toolkit, but her “eat your own dog food” bullet point hints that the doc is delivered via their wiki engine. (Sarah, do correct me if that’s an inaccurate leap in logic.)

But, if the product you’re documenting isn’t itself a wiki, you’re going to need to evaluate tools. I borrow directly from Don Day’s editor evaluation heuristic for a methodology for evaluating a writing and publishing toolkit to fit in an Agile environment. Evaluate a tool (no matter what you’re trying to deliver or how you’re authoring it) using “cost/benefit judgments on the features that mean most to your intended scenarios, business rules that need to be supported, and the willingness of your team to learn some new ways of doing things.” Well stated, Don, and whether you’re trying to find the right DITA toolkit or the right Agile toolkit, scenarios and business processes are quite useful. Anyone have great authoring or publishing scenario or business process suggestions for the XTW?

What makes a doc plan Agile?

Does working in an Agile development environment change the documentation plan, or user information plan?

For many writers, the purpose of a doc plan is to inform the stakeholders what you (or your team) intends to deliver for docs for a particular product release and when you will meet key milestones.

Here’s an outline of a typical user information plan that includes signoffs from interested parties, with the goal being that you work with your team to agree to what information deliverables are necessary for a software release to be complete.

  1. List of deliverables
  2. Risks and dependencies
  3. New features
  4. Documentation milestones and deadlines
  5. Techpubs expectations and assumptions for meeting the deadlines

That outline was from an actual doc plan from about three years ago. It was feature-dependent and waterfall-driven.

In an Agile environment, the doc plan might be more minimalist, listing only:

  1. key players
  2. release theme and top features in the release
  3. dates

Then the real work of planning the details of what needs to be addressed in the doc happens during iteration planning. The detailed planning may not be written down in a doc plan, spending the time on writing the end-user doc instead.

I suppose the most Agile doc plan would be a simple verbal agreement to what will be in the doc each iteration.

If there’s a sliding scale, what is the least Agile doc plan? What is the most Agile doc plan?

Making the documentation cruft calculation more user-friendly

Our tech pubs group enjoyed Scott W. Ambler’s “Calculating Documentation Cruft” article in Dr. Dobb’s Journal related to Agile methods and documentation. We had some fun in an email thread and I’d like to capture some of our discussion here.

Scott cleverly turns CRUFT (a geek term that either combines crust with fluff or refers to a lab where useless objects piled up in the hallways) into a measuring stick for the effectiveness of documentation:

  • Correct = The percentage of the document that is currently “correct”.
  • Read = The chance that the document will be read by the intended audience.
  • Understood = The percentage of the document that is actually understood by the intended audience.
  • Followed = The chance that the material contained in document will be followed.
  • Trusted = The chance that the document will be trusted.

Typically, I focus on Agile and end-user documentation, but Scott dwells on the type of documentation that you use while developing the software. Knowing that the Agile manifesto doesn’t value comprehensive documentation over working software, the fact that he’s calculating cruft in a document is refreshing and unexpected. However, my co-worker Shannon Greywalker and I both thought his algorithm could use some refinement. Shannon, being a math whiz, was able to re-mix it and gave me permission to post the idea here.

Shannon says “His formula is essentially 1 – (C * R * U * F * T) = a flat percentage “cruft” rating, wherein higher values are worse.

Let’s assume a perfect score for all 5 values (100% or 1.0 for each). It’s 100% correct; will have a 100% chance of being read; and will be 100% used, followed, and trusted.

1 – ( 1 * 1 * 1 * 1 * 1) = 0.0 = 0% CRUFT. An ultimate low score and so far so good.

Now let’s assume a 99% score for all 5 values:

1 – (.99 * .99 * .99 * .99 * .99) = 0.049 = 4.9% CRUFT. Our score has jumped almost +5% from 0. Still looks okay, mostly…

But now let’s assume scores of 40%, and 30%, for all 5 values:

1 – (.4 * .4 * .4 * .4 * .4) = 0.989 = 98.9% CRUFT.

1 – ( .3 * .3 * .3 * .3 * .3) = 0.997 = 99.7% CRUFT.

The curve produced by his formula is sharply logarithmic instead of linear. Logarithmic curves are the hardest for most of us to use in everyday life just because most of us can’t natively compare one logarithmic value to another.

The best example of an original formula that is not human-intuitive and therefore not all that useful is the Richter scale for earthquakes. The average layperson has no idea what those numbers really mean because 6.0 doesn’t sound that much worse than 5.0 – but it is much worse, because the Richter’s a logarithmic scale.

A more straightforward, intuitive, and linear results curve would be expressed by the formula:

1 – ((C + R + U + F + T ) / 5)


With a 60% score in all 5 factors: 1 – ((.6 + .6 + .6 + .6 + .6) / 5) = 0.4 = 40% CRUFT
With an 80% score in all 5 factors: 1 – ((.8 + .8 + .8 + .8 + .8) / 5) = 0.2 = 20% CRUFT
With the scores from Scott’s example: 1 – ((.65 + .9 + .8 + 1.0 + .9) / 5) = 0.15 = 15% CRUFT ”

I would take it one step further, with these descriptive ratings:

40% CRUFT, “document is getting a little crufty” rating

20% CRUFT, “the cruft hasn’t yet overtaken your doc” rating

15% CRUFT, “this document is approaching cruft-free” rating

Shannon’s argument is a good one, the best way to increase the understandability of the CRUFT rating for documentation would be to create a linear calculation for it.

Shannon also argues that there should be a weighting factor for each of the five factors used in scoring a cruft rating. Now, I say that people would disagree on which factors are the most valuable in a document, so weighting might overly complicate the calculation.

I also find the weighting to be too subjective because it seems that Correct could influence Trusted (docs that are found to be incorrect are then distrusted). Also, Understood is elusive for a writer to measure and also to target that specifically – if a selected audience member doesn’t understand what you’ve written, is that always the fault of the writer?

I do like Scott’s tips for creating less crufty documentation, most of which can also be translated for end-user doc. Here’s my attempt at translation for end-user docs.

Scott says “Write stable, not speculative, concepts.” Scott’s talking about writing conceptual information only when its factual and can be trusted. For end-user doc, sometimes writing the concepts out helps you uncover problems, so I would argue that it’s better to write some concepts even early on.

Scott says “Prefer executable work products over static ones.” Scott’s talking about using test executables for code rather than documenting the code and its limitations. For end-user doc, I think that an executable work product could be a screencast or live demo sandbox that lets people try out a feature safely, or perhaps having a link in the online help that opens the dialog box in context like Windows Help in Windows 98 that would open the Control Panel being described in a task about setting display resolution.

Scott says “Document only what people need.” Amen, brother, preaching to the minimalism choir. Know your audience before you write down words that will be cruft.

Scott says “Take an iterative approach.” All writers know that re-writing is as essential as writing.

Scott says Be concise.” Agreed.

What are your thoughts about calculating documentation cruft? Are we taking it way too seriously, or is there a good tool in this (possibly crufty) post?

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 MappingTM
  • 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.


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.


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 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 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.