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.

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.

47 Comments

  • Craig
    July 6, 2007 - 1:11 am | Permalink

    Thanks for a very useful article! I’ve been documenting in an Agile environment for about 18 months now, and while I’ve adopted a lot of your recommendations, it’s great to see that other writers are thinking along the same lines. And there were some great tips in there that I hadn’t thought about.

    I’m in a very interesting role right now – using Agile methodologies to document an Agile project management tool. I’ve found that if you go with the team’s flow (without doing the whole Documentation Plan up front), it’s a very efficient way to create documentation.

  • Helen Baker
    July 6, 2007 - 9:19 am | Permalink

    Hi Anne

    Thanks for taking the time to write this article – very useful. Our department has just started using the SCRUM methodology and your hints and tips will definitely help us as we start to change our working practices.

    Helen

  • July 6, 2007 - 1:29 pm | Permalink

    Craig – I have a post I need to publish about user information plans and Agile. One of the reviewers of our article, Melody Locke, noted that over time her doc plans became more and more streamlined. I’ll work some more on that post and would love to see what you think.

    Helen – I’m so glad you found it. When we wrote the article we had a writer like you in mind, trying to help others avoid the frustrations we had at times. And now that we’re both pretty enthusiastic about the methodology, we wanted to share that as well!

  • July 10, 2007 - 12:48 pm | Permalink

    Fascinating. I’ve recently switched to a company that employs Agile methodologies and I’m currently referring to our documentation process as “trickle” (as opposed to waterfall.. a shoddy metaphor I know).

    I am documenting what I learn as I go along, so it’s good to see that what we do here isn’t too far from what is beginning to be accepted as “industry standard”.

  • Mike
    July 10, 2007 - 2:04 pm | Permalink

    Anne:

    As you know, I’m leading a big team doing Agile Doc Development. We’re keeping afloat by having one writer assigned to each new feature (think product) and me doing all the scut-cleanup work. This seems to be working well although one of the big problems with Agile Development is Engineering defining Done.

    We’re about to go into Stabilization (although we have been told that we’ll also be getting new features in August) so I’m reverting back to what we know how to do for the last 8 weeks – plan, execute, and load balance on Doc’s schedule not on the Sprint Schedule.

    We’ll continue to do the Sprint planning and RallyDev but the plans we execute against will be the old-fashion end-of-release stuff.

    Doc needs heavy lifting for the last 6 weeks, not a damp cocktail napkin.

  • Pingback: Making the documentation cruft calculation more user-friendly « just write click

  • August 14, 2007 - 11:12 pm | Permalink

    My team has been working in an XP environment for a couple years. I really like your straightforward description of what process you use. A bit more organized than our approach ;)

    We’ve also added a fluid localization process to our development, which was very challenging to get off the ground, but well worth the results.

  • Pingback: Odds and Ends | Idiotprogrammer

  • Karen Bertram
    January 8, 2008 - 9:13 pm | Permalink

    This is a really good article. We’ve been scrumming for a little over a year and feel we’ve adapted pretty well. What suggestions might you have if development expects no lag in documentation? In other words, they expect product docs to be “at par with the code” at the end of a sprint?

  • Lorraine Sharon
    March 6, 2008 - 7:44 am | Permalink

    We are about to embark on agile development. The information in Anne’s article is very helpful.
    My question is the opposite of Karen’s. That is, what suggestions might you have if development wants some documentation to lag after a sprint is complete? In other words, they are suggesting that not all documentation must be done at the end of a sprint and the reviews and completion could happen some time later.

  • March 6, 2008 - 9:06 am | Permalink

    Hi Karen – sorry I hadn’t answered your question sooner. I think it’s difficult to keep up with dev if your publishing and/or review tasks slow you down – like if you have to “build” a “book,” write an index, and those are slow tasks, you’re going to have to figure out a faster way to publish. Plus, how much review is required of the docs? That answer matters as well. Since it has been a few months, how is it going?

    Lorraine – good question! My only advice would be to ensure you have an iteration where you get time for review with the developers and quality assurance people since “some time later” might be poorly defined. :) The other difficulty it might introduce is that a developer who has some essential information for you has “moved on” mentally from the item you’re trying to document, and his or her memory will be fuzzy. Those are just pitfalls to avoid, though, and in reality, it works well for doc to lag.

    Anyone else have suggestions for Karen and Lorraine?

  • April 15, 2008 - 4:17 pm | Permalink

    Thanks a lot for your article, Anne. We’ve been using quite a few of your recommendations for our project. I am so glad to find other people dealing with the same problems we have. I currently lead a small group of techwriters working in Scrum teams and I have to coordinate the production with 3 more development sites.
    Referring to the open question, that is how to “lag behind” a bit, I may contribute commenting that we try to apply common sense and not to conform to a rigid rule. I think that is the spirit of the agile approach for software and for documentation as well. I noticed teams tend to find their own way to work and I guess that’s OK as long as they are efficient. Of course, always make sure that the “delayed” documentation tasks are accurately included in the sprint backlog, both for authoring and reviewing (BTW we keep the editing activities outside the scrums, any other experience on that?). In other words, the team should agree how to work on each documentation item and just plan the way they think is the best.

  • Pingback: STC2008 - Wrap up STC Summit trip report « just write click

  • perry
    August 29, 2008 - 11:05 am | Permalink

    Stumbled onto your article on the web. here is my probably dumb
    question:

    AGILE is a software development process, this I know and learning and different from SDLC. However, I recently was chatting with another tech writer and they were telling me that they use AGILE for a centralized document repository for all their docs. So, is there also a software program called Agile that companies install for doc control and
    management?

    I have also been on interviews where Agile experience was needed.
    Thinking it was about software development, I said yes, but later it sounded like a doc control and management software that the company used.

    Now I am confused.

    If there is no such program doc management and control called Agile, what are these people referring to?

  • September 1, 2008 - 8:02 am | Permalink

    Hi Perry – not a dumb question at all. I haven’t heard of an Agile document repository, but it may exist. There are companies in Austin like Borland who are trying to create software to help development teams manage the entire product lifecycle, and I’m certain that a document repository is part of that management. It’s also possible that there’s an internal tool called Agile that is used for document management. I’d ask the interviewee if they mean Agile development.

    If you look at this post from Tech-wrl, http://lists.techwr-l.com/pipermail/techwr-l/2008-June/030276.html, you’d see a reference to Agile Advantage 2006, and it appears to be a system that works well with Agile development processes, so there is a tie-in there. Thanks for bringing it up – it’s a new product to me and probably others who will read this article.

  • Pingback: What do I need to do to write Agile documentation? « Orion Spur

  • Becky Williams
    September 12, 2008 - 11:17 am | Permalink

    What a great article! We’ve been using Agile Scrum for about 6-7 months. Luckily, I’ve incorporated most of these practices so far and, after the initial adjustment, have found it to be a great way for me to work. Writing doc plans is one area where I could improve, so I’ll be looking for Anne’s other article on that topic shortly. Here are a few thoughts I’d like to add:

    - I’ve started working with UI developers to add well-written tooltips for all web forms. This allows me to write procedural topics in Help that allow me to focus on key parts of the procedure rather than what each field does and how it needs to be completed.

    - Most of my documentation is completed at the same time as development. I focus on drafting procedures and key concepts with development reviews (while it’s on their mind) during the sprint. Topics can be fleshed out more later, if necessary. QA and business analysts review documentation more during hardening sprints to check flow and look for missing pieces. Of course, what Piero said about using common sense is key.

    - In terms of tracking tasks, I try to keep mine with the development tasks because of visibility, but I also add documentation stories for tasks that don’t necessarily fit in that model. I attempt to put more emphasis on those tasks that do align with development tasks whenever possible. I’ve seen that this helps me be more a part of the team, and developers are more supportive of the need for documentation as well. Non-dev doc tasks can be more easily addressed while waiting for reviews to come back or during testing.

    I’m currently working as part of two Scrum teams that are on the same 2-week sprint schedule. In addition, I have non-sprint tasks, so things get a little crazy from time to time. I appreciate all the tips and look forward to hearing more. Thanks!

  • Francis
    July 9, 2009 - 8:43 am | Permalink

    Hi,
    Very interesting discussion!
    My team is going into agile development. I am alone with several products, and I also do other things apart from tech doc, so I am trying to keep the workload as low as possible. People are now putting pressure on me to produce versions of documentation at each iteration (every 2 weeks). I am trying to explain to them that that’s trying to shoot at a moving target and will imply a lot more work than producing a version of the documentation once the development process is stabilized. My reasoning is that If you try to follow each one of the changes in user interface, you will end up doing and undoing the same thing again and again…
    “documentation should intervene as late as possible in the software workflow” has been my motto for years.
    How to do deal with this type of problem? How often do you produce output?
    I use AuthorIT and outputting a doc version is quite time-consuming: generate .doc and .chm, compile .doc to .pdf, copy/paste into external folders…

  • July 9, 2009 - 6:35 pm | Permalink

    Great question Francis, and you’d like the discussion going on in this thread at The Content Wrangler Communities’ Agile Documentation group: http://thecontentwrangler.ning.com/group/agiledevelopmentandtechnicalcommunications/forum/topics/question-of-the-week-how-1.

    As you might imagine, the answer is, it depends. It depends on the maturity of the product, and how detailed the designs are up front, and whether you’re on a team that tends to throw out first prototypes that are coded. It also depends on how modular and topic-oriented your documentation is already.

    Your deliverable description is also interesting – not many Agile shops that I know of would be manually generating doc, instead it would be automated (even the file copying), and maybe part of the product build. So you may also look into automation so the process is less manual and time-consuming.

    Hope that helps! I’d encourage you to post your question to the Content Wrangler Community as well to get more perspectives.

  • Francis
    July 10, 2009 - 8:08 am | Permalink

    Thanks Anne,

    Yes, that discussion is useful: at least I can confidently say that there’s no standard up to now (my management is very much into doing things “the standard way”).
    Doing automatic generations is a bit complicated for me as AuthorIT and Acrobat both have tendencies to freeze in the middle of a generation, requiring manual re-starts.
    I think the real questions are
    * when will anyone actually need the documentation?
    * when will anyone actually read the documentation?
    * when is the latest date when I will have time to produce the documentation before outputting to real clients?
    In my organization, the iterations stay within a small circle of people inside the company, who aren’t great documentation readers.

    Cheers,
    Francis

  • Pingback: LiveTechDocs - Documentation collaboration service

  • Jenny
    September 13, 2009 - 12:39 pm | Permalink

    Gosh, Anne, thanks so much for this exploration! I come from a “waterfall” environment and am interviewing with a company that employs Agile. Without having used that name per se, they stated they organize features into stories and two-week windows. (Again, not having known that was Agile)I immediately determined to construct some sort of plan for attacking the documentation, trying to reconcile the two models. While surfing for clues I came to the conclusion that they are employing Agile, and then came upon your page. Great discussion, just in time. I will also check out Content Wrangler. Thanks again!

  • jojomonkey
    September 14, 2009 - 3:24 pm | Permalink

    thanks, i’m reviewing customer documentation as we speak in an agile dev. env. and was asking myself that there has to be a way to get our doc. team to jive better w/ our dev. model. i think this article is going to really help, esp. if people integrate it.

  • September 14, 2009 - 3:28 pm | Permalink

    Wow, great that this article is still so helpful 2 years after we wrote it! I revisit the concepts myself now that I’m back as a writer embedded Agile team. Just last week I mentioned to someone trying to figure out how book-based PDF files could be more Agile, and found myself saying, do a content audit to find out what could be the topics in your new doc deliverable. Then I found myself attempting a content audit as well. It takes a lot of fine-tuning along the way, also.

  • Becky Williams
    September 23, 2009 - 11:28 am | Permalink

    Over the last year+, I have found it easy to write in an Agile way when it comes to the development tasks that occur during the sprint; however, I often have difficulty with tasks that continue for more than one sprint or do not rely on interaction with developers at all.

    Recently, I found an easier way to handle one such item…Release Notes. I estimate the entire task of creating Release Notes, then I divide that estimate by the number of expected sprints before functionality is delivered to clients. If the estimate is not easily divisible by that number, I add any extra time to the final sprint. During each sprint, I have a Release Notes task. In the first sprint, I create the document and add bug fixes/enhancements that are developed during that sprint. Reviews of this work should also be completed durint sprint one. When the sprint is finished, this part of the doc should also be finished. During each sprint, I add the part of the work that pertains to that sprint, and during the final sprint, I get final reviews and publish the doc in PDF. We use MS Word’s Track Changes feature to help reviewers know what is “new” for that sprint.

    Hope this helps!

  • Karina
    October 15, 2009 - 3:50 am | Permalink

    Thanks for this article, which I just now found! I am documentation manager at a smallish company and have a team of 8 tech writers who all work in their own scrum teams. My company adopted agile last year and so far it works very well. The problem is, that some people in my company are extremely scrum enthusiastic and want to follow it to the point (which is also good). So they are saying that in a scrum team everyone should do everything, meaning, that teach writers should be able to do development and testing tasks, developers tech writing tasks etc. Even though I have been trying to ask them if they the would be willing to train the tech writer to learn Java or send the developers to an English class (my company is in Finland, documents are written in English), it’s not helping. I have been trying to find resources on the net that would say (apparently if it’s written on Internet, it’s true) something about this and possibly back my point, but I haven’t found anything. Seems that everyone else takes it as granted that writers (who have no experience or interest in software development) don’t write complex code. Has anyone come across this problem?

  • Becky Williams
    October 15, 2009 - 12:40 pm | Permalink

    Karina, our team is probably somewhere in the middle on this issue. We have team collaboration in terms of sharing ideas, for sure, but not true job sharing.

    Also, as a technical writer, I frequently log bugs I find, although I am not following a test plan or covering an entire area of the app. I have also pointed out misses in terms of requirements that can sometimes get us off track. And, I sometimes get notes from developers who have input on how Help is worded or what content is included.

    This being said, I don’t have it in my plan to learn development other than how it relates to documentation and/or training.
    There are some borderline cases where I may need to learn a bit of development in order to get something I need implemented for doc/training because the dev team doesn’t have experience in that area.

    Is this what others are experiencing?

  • October 20, 2009 - 12:12 pm | Permalink

    Hi Karina – thanks for posting, and I’m glad the article is helpful!

    I am once again on an Agile development team, and we are running into something similar I believe. There are heavy development tasks that I can’t do, but I would like to learn more about how to do them. So I am taking small steps towards learning more about the “guts” of the product I document. For example, since we work on a web application, it’s good for me to work on CSS bugs that come onto our board, if a developer is not available. I think the main thing to do is to be available and ready for any task – I don’t think you need to send your writers to special training for specialized development tasks. I think it’s okay for each team member to have a specialty. My specialty happens to intersect with web applications since I know web content management (and styling) well. I also test quite a lot (let me emphasize A LOT), following legacy test plans when it makes sense (we’re not creating new test plans in our Agile environment).

    So, as usual, it depends on the product you’re working on. Are there any small-ish development tasks that are entry-level? Maybe start with those. But also realize you can keep training writers in their specialty and not ask them to become newly-trained specialists in programming or testing.

  • August 3, 2010 - 9:21 am | Permalink

    We are currently trying to staff a Agile team. In the past, we’ve had a mix of writers (senior, intermediate, junior, offshore) yet it appears the Agile process demands more senior writers. Does anyone have an opinion on that? Thanks!

  • Pingback: Where’s the forest? « Write Trends

  • Pingback: Information Development : Information Development Agility: Creating User-Centric Documentation – Part I

  • Pingback: Information Development : Information Development Agility: Creating User-Centric Documentation – Part II

  • Pingback: Information Development : From Zero to Sixty, Building a Help System from Scratch

  • Pingback: Documentation Is Your Product « blog.dexy.it

  • Pingback: Daily post (weekly)

  • Claudia
    July 25, 2011 - 10:18 am | Permalink

    In the work environment I work, these rules / tips are really hard to follow, as the R&D is on a (physical) different site than the team(s) writing the documentation. Also organization-wise, they are in completely different units of the company, so they have to collaborate as a virtual team both from an organizational and location POV. I’m neither part of any of the teams, my role is to take Care that things get done. But this is really challenging in this kind of team set-up. Any advise from anybody what could be done in such a situation to make the documentation available at launch (and not couple of weeks later)? Also need to mention here that resources are limited, so an own technical writer for the project is probably something that’s not going to happen.

  • Robin Senor
    December 12, 2011 - 3:29 pm | Permalink

    Annd!

    I love your article- it is so helpful and its refreshing to know I can throw out those obsolete Information Plans.

    I do have a question that is along these lines, though kind of in a different vein. I have long used Adobe Framemaker (and the Technical Communication Suite) to generate PDFs and web-based help. With the exception of the integrated (single-sourced) help system, my book production stands independent of the product production.

    I will soon be starting a position where the documentation department is me myself and I, and I am being given pretty much free choice to decide how to handle the department, how to author, and in what formats to publish. I also need to put all their material together ASAP.

    I am so accustomed to Frame (and review cycles using it- including my own internal), so I’m hesitant to move in a different, and unfamiliar, direction. But… I also recognize the LT benefits of storing content in DITA. That being said, I see more and more plug-ins between Frame and other platforms for user communication (Confluence) and…for the forseeable future, I don’t have help on this team.

    Sorry to go on – I know this is rather off topic. But any tool – and process – advice would be so appreciated.

  • Robin Senor
    December 12, 2011 - 3:32 pm | Permalink

    Oh, and I should clarify- its an Agile shop with a very rapid release cycle (though it is enterprise software and most of the releases are patches).

    To those above who discuss regular publishing, I might suggest putting together some standards as to when you update your core material and when you do not. For example, if your company tends to only put fixes in patches (obviously ideal) then your policy should be that patches do not get documentation updates under any circumstances…

  • Pingback: agility active

  • Pingback: Writing Effective Documentation For WordPress End Users | TheSite.me

  • Pingback: Effective Documentation Writting For End Users Of Wordpress | WordPress Planet

  • Pingback: Writing End-User Documentation in an Agile Development Environment | #plesk.writer

  • Pingback: Writing Effective Documentation For WordPress End Users - Goodfav Howto

  • Pallavi
    March 4, 2013 - 11:59 pm | Permalink

    Loved your article. Very useful. Would you have advice on Writing documentation for the PS – Professional Services group of an (afotware/hardware) organization? This group is mainly involved in post-factory implementaion of the product at the client site. How can you understand the requirements for this group and the documents to produce for them – implementation guide, practitioners guide? Is there a standard approach for planning the doc set for this group. Your advice will be apprecaited.

  • Pingback: Sites at Penn State Help | Documentation Guidelines For the Sites At Penn State Team

  • Pingback: Writing Effective Documentation For WordPress End Users | Smashing Magazine

  • Pingback: Agile & Tech Comm: Creating Task-Focused Content

  • Leave a Reply