Developing a workable documentation process by “being” Agile rather than “doing” Agile
Don’t just do Agile… Be Agile
The title of this presentation is a bit misleading. If you read up on any Agile methodology, you will find that there is very little written about documentation. That’s why I like to apply the spirit of being Agile rather than “doing” anything specific.
The Advent of Agile
Agile started in Februrary 2001 when 17 practitioners from different methodologies came together on a trip to the Utah mountains to ski and relax and try to find common ground. Because of the wide differences in their approaches, the didn’t expect to agree on anything substantive.
At the end of the weekend, they were supprised at the outcome and at what they had agreed on: which were the four value statements and the twelve supporting principles which together became the Manifesto for Agile Software Development.
What is Agile anyway?
Individuals and Interactions
over processes and tools
Agile values individuals and interactions over processes and tools. The best way to convey information is by talking face-to-face, which is why Agile teams try to be co-located and self-organizing.
Agile values working software over comprehensive documentation. It’s not that documentation is ignored, but preference is given to the software and to documentation that is a living part of the process. Working software is the primary measure of success.
over contract negotiation
Agile values customer collaboration over contract negotiation. Business people and developers should be working together daily – which is why you will often find customer representatives on the team… Agile methods stress customer involvement.
Responding to Change
over following a plan
Agile values responding to change over following a plan. Changing requirements are actually welcomed, as they are an opportunity to iterate closer and closer to what the customer really needs. This doesn’t mean, however, that Agilists don’t plan – but planning often involves 3x5 cards with user stories on them.
Continuous attention to technical excellence and good design
Agile processes are intended to promote sustainable development so that a constant pace can be maintained indefinitely. Agility is also enhanced by continuous attention to technical excellence and good design.
Self-Organizing Teams Reflection and Improvement
Simplicity is the art of maximizing the amount of work not done. Teams that are self-organizing produce the best architecture, requirements, and design and, at regular intervals, the team reflects on how to become more effective, and adjusts its behaviour to become more effective.
Methodologies are Prescriptive
The different Agile methodologies are as prescriptive as any other methodology. They all have various practices that they recommend, and which are designed to help you to achieve better results.
No Prescription for Documentation
However, there is very little about documentation practices – except for how to write better user stories and use cases.
So what does it mean for technical writers?
Many practitioners actually include technical writer as one of the roles in an Agile team… the key concept here is that the writer is actually a part of the team – not separate from it. That means participating in daily meetings and interacting with the engineers.
The biggest difference is the Mindset
This can require a change in mindset if you are used to coming in, writing the documentation, and then moving on to another project. On an Agile team, you would be participating in the development process, being the voice of the user, and writing documentation in parallel with the development work.
Integration with the Development Team
Agile teams are cross-functional, so there are plenty of places where technical writers can contribute skills that are complimentary to the skills of the engineers.
KIS and KIL
and a dollop of Horse Sense
You have to be flexible. Keep it simple, and keep it light. Don’t try to bend the process to fit the documentation, adapt the documentation so that it works with the team and the culture, and delivers only what the project needs.
Documentation should be “Fit for Purpose”
The documentation should be just enough, just in time to fulfill its purpose… and “good enough” is often the measure of success. Use the documentation as part of the testing, so that becomes part of the process.
Focus on Users and their Needs
Because technical writers usually have a good understanding of the users, they can often help with task analyses and designing workflows. Writing documentation also usually brings with it a good understanding of the behaviour of the system from the user’s perspective. You can use this knowledge in testing.
Develop Design Patterns
Develop design patters for documentation components, much like engineers use design patterns for common system components. Create templates with reusable sections that can be mixed and matched. By the way – structured content doesn’t have to mean DITA. Create templates for units of structured content that you can copy and paste and fill in the blanks.
Design for Change
Try to write things once and put them in at an appropriate place in the information flow, then reference them from other places. Cover single tasks from end-to-end, then create a “cookbook” that strings the single tasks together to cover units of work.
and Markers… and Cameras… oh my!
The tools can be simple… personally, I love my digital camera, and I use whiteboards – a lot.
The Agile Manifesto is available online at: http:// www.agilemanifesto.org