[Agile Guide] – Agile for Technical Writers

We don’t often hear about the trials and tribulations of a technical writer. Frankly, that’s a space that may need more bloggers like Giri from IWorkAsATechnicalWriter.com to provide more valuable free content for other professional technical writers.

In Scrum, for example, we only really hear about three main players: The Scrum Team, the Product Owner, and the ScrumMaster. What about other players? In some businesses, technical writers are crucial to the entire process as they design, write, create, maintain, and update technical documentation.

What is interesting here is that there is a larger idea at stake: The idea of documentation for companies that run their businesses in an Agile manner.

Ever work for the government or DoD? What’s that documentation process look like? Doing Agile on a major security project that needs tons of documentation on development for audit reasons? Ah, the list can go on and on.

So how in the heck do you update and maintain technical documentation in an Agile environment when everything is subject to change?

Giri has some thoughts on it. Below are his ideas distilled.

In an Agile environment, given that:

  • Each product is different in complexity.
  • Planning and requirements may not be clear.
  • Each and every sprint is different.
  • Documentation for GUI-based manuals contrast with purely technical analysis.
  • Technical writers need to be able to provide just enough documentation for selected (prioritized) features.

An Agile technical writer, can:

  1. Wait till the end of a sprint, document only what is available.
  2. Leave room in your document for more text and planned features.
  3. Plan a Table of Contents to get the big picture of the entire product.
  4. The Table of Contents should come from each prioritized feature.
  5. Ensure not to document while development is taking place (see first point in list).
  6. Do some topic authoring. Pre-write any information needed for each feature.
  7. Keep source diagrams and screen captures in a safe place. Keep duplicates for editing.
  8. Keep content you write for concepts in a separate place. You may revert back to them later.
  9. During interim releases or internal betas, give a list of things that you will deliver and no more. Some modules will not have content and that’s fine.
  10. If you can, maintain a document WIKI and ask the SMEs or Product Owner to collaborate and provide their comments.

Some final points:

  1. Some writers follow a “write once in 2 months” approach. This is a good approach too provided your project management agrees.
  2. Ensure that you have a detailed review only every 3 months or so when some parts of the product is frozen.

Some great points here. We’d like to see more written about Agile documentation in the near future. Let us know if you have any suggestions on this topic in the comments below!

[HT: IWorkAsATechnicalWriter]

6 Replies to “[Agile Guide] – Agile for Technical Writers”

  1. Cannot say this was really an “Agile” effort since it occurred in the late 70’s, but the way we worked with the (user) documentation folks was “agile” in its approach. It was a large, mainframe app;lication for doing ad hoc reporting and records management uaing what was then called a 4th generation or non-procedural languge.

    We had a large annual feature release every year based on customer feedback on what they were looking for. During a very substantial “rewrite” of the product during which we were also adding a lot of new user functionality. Each week for a period of many months, we’d meet with the marketing rep and the tech writer (as they did the user docs and were under the marketing arm of the company). We’d discuss what the rep said the customer needed and review how we saw implementing it, including suggesting other things we felt could be included as capabilities very easily while we made the changes needed for what the rep described. While this discussion went on the tech writer basically evolved the user doc additions for allthis new work. No actual requirements were ever written and the user doc changes became, in effect, the description of what was needed and, from a user perspective, how it would work.

    I think it was the first time the user docs were ready exactly when the software was done (in fact, ahead of time, since the last couple months were extensive system-level, regression testing and some demos for key clients).

  2. To give you insight into the extremes of documentation, the Federal program I am advising currently has 29 CDRLs. Yes, that’s twenty-nine individual documents. These documents, some of them delivered monthly, are required per the contract. Someone at the inception of the contract thought it would lower risk by having more documentation. What has happened is the program generates paper rather than value. It is hard to describe the level of rework being committed for each document.

    I really like your idea of maintaining a document WIKI, asking the SMEs or Product Owner to collaborate and provide their comments. I proposed this at my last engagement but didn’t get to see it happen. Though my current customer does provide comments toward each document, they lose track of the proposed changes by the time the next CDRL is delivered. Serial communication methods like this just don’t work.

    1. Exactly. Wiki’s are great resources that can be updated by the right people constantly. The reason why paper work is (sometimes) useless is that it takes such a huge amount of work to put it together (over months!) and two things happen at the completion of the document:

      1. Nobody reads it
      2. The system has already changed way beyond the documented specs.

      I saw this at the airforce as well. Ridiculous. Documentation should not be a burden, it should be a nice augment!

Leave a Reply