This is a tough topic to research. Using the words “agile” and “documentation” in the same search query returns a mixed bag of results. Some citing that the Agile Manifesto‘s goal of “Working software over comprehensive documentation” to mean that Agile products need little to no documentation. A more realistic and practical interpretation of that line is to treat documentation as any other component of the project.
A project or product should not have features that do not add value. It should not have code that doesn’t add value. Nor should it have documentation that doesn’t add value.
I’ll go along with that, but when it comes to reading what others have to say about technical writing, searching for “agile technical writing” returned this collection (in no particular order):
- Agile 101 for technical writers – gives you a good flyover of Agile terms and concepts but nothing to help the technical writer work in the environment.
- Agile Technical Writing Basics – offers a short summary of the pros/cons of agile technical writing.
- Technical Writing In Agile Software Development – provides a tantalizingly brief view into technical writing in an Agile software development shop, but moves on before getting into any nitty-gritty (even after parts two & three).
- A Writer’s Guide to Surviving Agile Software Development – provides a first-person look at Agile technical writing, but suggests some disturbing best practices like “pad estimates,” “extend deadlines,” and, my favorite, “hire more writers.”
- Agile Technical Documentation – is a rather extensive essay on various aspects of technical writing in an Agile environment. It provides a good view of the entire process from a writer’s perspective.
- The agile technical writer and it’s follow up post, The agile technical writer II – provide another first-person look tat being a writer in an Agile software development shop.
- Agile and Tech Comm: Writer Challenges in Agile and Traditional Development Teams is another first-person look at being a writer on an Agile development team, and it has some more links at the end of the article.
- Writing End-User Documentation in an Agile Development Environment – has some great points at the end of the article.
-
Best Practices for Agile/Lean Documentation – describes documentation in the context of an Agile development environment.
That’s quite a list and a range of perspectives. They range in age from 2 to 12 years old, with an average of 6.3 years.
Some early observations:
- The earlier ones seemed to explain Agile more than the more recent articles.
- They all offered tips for writers in one form or another
- About half were written as first-person experience reports and the other half in more of a third-person, instructional format.
- Most were written in a narrative format with a few as just bullets or bullets with some details.
- Only a few cited additional references (although most had embedded links to related topics)
I’m not sure what conclusions to draw from this, yet. For perspective, I wanted to do a similar survey of academic literature, but searching for “Agile technical writing” didn’t produce much to read. Hmmmm….