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:
- Wait till the end of a sprint, document only what is available.
- Leave room in your document for more text and planned features.
- Plan a Table of Contents to get the big picture of the entire product.
- The Table of Contents should come from each prioritized feature.
- Ensure not to document while development is taking place (see first point in list).
- Do some topic authoring. Pre-write any information needed for each feature.
- Keep source diagrams and screen captures in a safe place. Keep duplicates for editing.
- Keep content you write for concepts in a separate place. You may revert back to them later.
- 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.
- If you can, maintain a document WIKI and ask the SMEs or Product Owner to collaborate and provide their comments.
Some final points:
- Some writers follow a “write once in 2 months” approach. This is a good approach too provided your project management agrees.
- 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!