In our current project we have pushed documenting it (other than deep technical detail) out to the end of our sprints. Is this a sensible plan?
Technical Writing for Agile Teams
The Agile Maifesto values:
Working software over comprehensive documentation...[T]here is value in the items on the right, [but] we value the items on the left more.
So, what does that mean for technical writers on a cross-functional team? In my experience it means:
- Adequate documentation (whatever that means for the team/project) should be part of the Definition of Done.
- Code should be as self-documenting as possible.
- Test suites should function as technical documentation to the greatest extent possible.
- Technical writers need to be involved in Sprint Planning to identify stories and tasks where additional documentation may be needed.
- Technical writers need to be involved throughout the sprint to coordinate with developers and testers to make sure that the team is communicating and coordinating about documentation requirements and deliverables that must be baked into the iteration.
- Anything that needs documentation should be designed and developed with documentation in mind, rather than treating documentation as a last-minute bolt-on.
Technical Writers are Full-Fledged Members of the Team
No member of the team should be a second-class citizen. It reduces team cohesion and efficiency to treat technical writers as anything other than integral members of a cross-functional team.
In addition to the social dynamics and the requirements of the framework, treating technical writers as first-class citizens ensures that:
- Documentation tasks will be baked into your process.
- Knowledge transfer between coders, testers, and writers will be a constant high-bandwidth stream, rather than a last-minute set of interviews where lack of domain knowledge will tarnish the deliverables.
Individuals have the chance to become cross-functional, not just the team.
- Developers should learn something about testing and writing.
- Testers should learn something about development and writing.
- Technical writers should learn enough about the technical disciplines to be able to ask meaningful questions when "self-documenting" code or tests just aren't.
If you find that you need technical writers to ensure the success of your project, then they belong on the team as valued and essential contributors and should be interleaved throughout your iterative processes. Once you've made the decision to include technical writers on the team, then their inclusion within the core group is one area where your mileage should not vary.