Recommended
More Related Content
Similar to The Agile Technical Writer: Fact or Fiction?
Similar to The Agile Technical Writer: Fact or Fiction? (20)
Recently uploaded
Recently uploaded (20)
The Agile Technical Writer: Fact or Fiction?
- 1. Introduction to agile for documentation MDDE 622 Assignment Collaborative Technical Writing Practices Dana West Publication date: November 23, 2012 (v1)
- 2. Individuals and interactions over processes and tools Working software over comprehensive documentation Customer collaboration over contract negotiation Responding to change over following a plan
- 3. Image: Bee Hive by Rebecca Leaman http://www.flickr.com/photos/rjleaman/2364448242/ CC BY-NC 2.0
- 4. Image: Meditation by Mitchell Joyce http://www.flickr.com/photos/hckyso/3870006964/ CC BY-NC 2.0
- 5. Image: “I Scrum Daily” t-shirt by AleNunez http://www.flickr.com/photos/alenunez/444510317/ CC BY-NC 2.0
- 6. Image: Tai chi in the morning - 7 by psit http://www.flickr.com/photos/psit/5253339905/ CC BY-NC 2.0
- 7. Continuous stakeholder feedback To deliver high quality code – and documentation ‘project’ chunked into use cases, stories and user roles through series of time-boxed sprints Image: Stopwatch by William Warby http://www.flickr.com/photos/wwarby/3296379139/ CC BY-NC 2.0
- 8. LEAN Agile Iterative SCRUM Image: Dolls in the Rain by Joe Lodge http://www.flickr.com/photos/joe57spike/5690570945/ CC BY-NC 2.0
- 9. Working code Iterations User scenarios Sprints Scrums User roles Image: BBC Micro User Guide by Jem Stone http://www.flickr.com/photos/jemstone/2348750617/ CC BY-NC 2.0
- 10. Ensure usefulness not conformance Image: thumbs up by Daniel Zimmel http://www.flickr.com/photos/devnull/359791913/ CC BY-SA 2.0
- 11. User stories > make documentation more task- oriented and organized Stakeholder feedback > make documentation more useful and effective Shorter cycles> Focus on what needs to be done - priorities Image: Luke Skywalker by Duncan Cumming http://www.flickr.com/photos/duncan/54069883/ CC BY-NC 2.0
- 12. Image: curtains by Julie Manzerova http://www.flickr.com/photos/julia_manzerova/4658243305/ CC BY-NC-SA 2.0
- 13. #1 – Take initiative # 2 - Increase your product knowledge and add value, become a know-it-all # 3- Advocate for the user – and the team
- 14. Increase your visibility and scrutiny Attend status/sprint meetings Take part in sprint planning Ask about documentation impact Spell out ‘done’ What are your ‘done’ criteria?
- 15. Learn and use the product/software I, user Extend your writing expertise to add value I, educator Keep them all honest I, terminologist
- 16. Apply timely customer input Track improvement Help the team Hold workshops on task-oriented topic writing, review process, guidelines and standards for writing, style guides and terminology
- 17. Collaboration rules It’s not about what the software does but what the user does Be a minimalist – give them what they need YOU add the clarity Image: Reminder 2 by bibliojojo http://www.flickr.com/photos/68509201@N08/6225701939/ CC BY-NC 2.0
- 18. References Agile Alliance. The Agile manifesto (2001). Retrieved November 22, 2012 from http://www.agilealliance.org/the- alliance/the-agile-manifesto/. Agile software development. (n.d.). Retrieved November 22, 2012 from the Agile software development Wiki: http://en.wikipedia.org/wiki/Agile_software_development. License: Creative Commons BY-NC-SA 3.0. T Agile wiki. (n.d.). Retrieved November 22, 2012 from the Agile Wiki: http://agile-wiki.wikispaces.com/Agile+Wiki License: Creative Commons BY-NC-SA 3.0.
Editor's Notes
- This presentation provides an overview about the characteristics of an agile approach to software development and how it affects the technical writer’s role in creating and managing user or technical documentation. It is intended to spark discussion about best practices for novice and experienced technical writers who are or may soon be working in an agile environment.
- Within a context of software development and project management, agile has specific meaning and implies different principles and methods. Let’s look at where this originated - the ‘agile’ manifesto - which was written over a decade ago by a group of programmers who were looking to articulate a more responsive approach to developing software. The first, individuals and interactions refers to putting more emphasis on self-organization and motivation and working in teams. The second, working software over comprehensive documentation can seem alarming to technical writers; it does not mean that documentation goes away, it just means you’re more focused on what needs to be done – working software and explaining the working software – one step at a time.The third, the focus on customer collaboration refers to how agile development embraces changing customer requirements. Compared with a more traditional waterfall method, where all requirements are articulated up front, agile proposes that requirements cannot be known at the beginning of a project and that they evolve over time. By creating smaller cycles of development that address the customer requirements, the idea is that there is less risk of developing software that the customer doesn’t like. Last point, agile is focused on quick responses to change and continuous development and improvement. The main goal of agile is to produce and ship useful, working software as early as possible to customers. This implies it has been tested and is usable – but not always - with the necessary documentation to support it. These cycles of development and delivery are known as sprints. Let’s look at how these agile characteristics affect the technical writer …
- Agile teams are known as self-directing teams where members are generally themselves responsible for working out how to get the work done. As a technical writer, you are accustomed to working with developers, customers and users but your role on an agile project requires you to increase your visibility and engagement. Standup meetings may or may not be part of your project as a way to get and receive status but definitely face to face conversation is vital with the team before, during and after technical reviews of the documentation. In some ways, reviews may work better in agile because they can be less formal and team members are reviewing your documentation at the same time as the code is being developed. Bottom line, you need to find strategies that work for you to get the information you need. The driver here is, if the documentation is not done, the sprint isn’t either.
- One of the goals of the agile method is working software. So there is a focus to create stable code by working on aspects of it day by day. The idea is that this method is sustainable, and agile teams can ‘pace’ themselves. When something works, it is ready to be shipped. If it is not, the team does not move on until it is fixed. That goes for the documentation too.
- Another agile characteristic is that there is a lot of communication and collaboration among team members and stakeholders. Everyone’s input on an agile team is critical, and a failure to communicate can mean time wasted.Scrums are just one technique to get everyone talking and sharing, join whatever status-reporting meetings there are to elicit and validate what you need to move forward with your tasks. An example of where communication is critical is the estimation process. Everyone on an agile team makes their own estimates about how long their work will take based on a certain user story or task. So speak up and let product owners know if you have too much or not enough work during sprint planning. Repeat, if the documentation is not done, the sprint isn’t either.
- This last point refers to responding to change, typically it means working at a sustainable pace … the change may prompt a quick response – but usually it’s all in the flow of how an agile team works, not always following a strict plan. For the technical writer, planning and delivering content and keeping up with the pace of change can be a challenge. Try to keep the documentation in sync with development during each sprint. Make sure that there is time for at least one nearly final or comprehensive review in the final sprint to make sure nothing was overlooked in the documentation.
- A quick recap… the main goal of agile is to produce and ship usable, working software as early as possible to customers. Working software is typically the measure of progress in agile. When something works and is useful, it is ready to be shipped. These cycles of development and delivery are known as sprints. Agile development also embraces self-directed teams and changing requirements. Some may say that agile development does not require user documentation. Don’t listen. Of course, documentation is still required, it may be in smaller deliverables, or as part of the user interface, online help, but it’s part of the code and is needed to so that the user can accomplish their work.
- Agile can be one of many methodologies at work on your project, for example, you may hear the words iterative, LEAN and agile also being used interchangeably.Don’t sweat it. These processes are sometimes interrelated. The gist is to do more with less. What that means as a technical writer on an agile project, is to adopt a minimalist essentialist approach. This may terrify you or make you happy. Try not to think too hard on the split between ‘user’ and ‘product’ documentation. It too is interrelated. Writing documentation is an iterative process, as we understand the software and our users, we go back and make improvements to the documentation. The idea of being ‘done’ and coming to the conclusion that ‘done’ sometimes means ‘good enough’ to release may be difficult to overcome. It’s important to figure out your ‘done’ criteria on the project and try to adopt a more modular approach to the content breaking down user guides into small manageable chunks.
- As the technical writer, you may still be thinking that you’re at the end of the software cycle and documentation is the last step, so what changes?Perhaps everything and sometimes nothing … depending on the project and how you see your role. Keep in mind that on agile teams, everyone can work and view any story. As a technical writer, you can play a prime part in keeping everyone honest and focused on the end user’s needs. Break down those user scenarios or stories into tasks. Give input - as time permits- into planning meetings, or into the design of a feature and how that affects other parts of the product. Use downtime wisely to get involved in other aspects of the project. With agile it’s especially important that other team members can update the document source so that the technical writer doesn’t block the team’s ability to complete.
- Technical writers develop quality technical information – that includes not just making sure you’ve got documentation that conforms to whatever they said to deliver in the contract but something usable. This doesn’t change as a result of agile.What’s usable? This means making sure that documentation… helps users do the tasks that they need to do to and are supported in the product. is easy to read and is unambiguous. is organized and information is easy to find. These are some characteristics of creating quality technical documentation. Now how to use agile to your advantage to do this …
- As outlined previously, here are a few examples of how you the writer can take advantage of agile in the writing process.Get involved in the user stories or scenarios. They help drive the organization of the document in terms of users, requirements and tasks. Get concrete about what they need to achieve and how to break it across sprints as needed. Continuous feedback and input allows you to get incremental insights and make incremental improvements – no more comments at the end of the release cycle. This can be a burden and a blessing. Embrace it. Shorter cycles or sprints mean you can work on the chunks of content that need to be done first so you can prioritize your work. Plan to have one final comprehensive review to look over the documentation during the final sprint.
- The beauty of agile – we’re told – is the transparency. This simply means that technical writers can see developers' progress – just as developers can see technical writers’ progress. This viewing and sharing status can be done through formal (e.g. bug tracking software) or informal (e.g. conversation, meetings) means.
- We’ve looked at some of the benefits and challenges of working on an agile project. What are some things you as technical writer can do to get yourself oriented to its ways and prosper?Here’s a quick list.
- Here are some activities you can take up at the beginning and throughout your project. Increase your visibility and scrutiny. It’s important to be in on sprint planning and attend the scrum activities or whatever status meetings you have in your project so you know what stories and defects will have an impact on the documentation. Review the done criteria for the user stories and determine upfront and revisit what documentation is needed to support the sprints.
- A technical writer typically approaches software or product as a naïve user and part of our job is to install, configure and administer whatever we need to write about, using the latest software build. First point, don’t just nitpick, get in there and be constructive and make the software – the user experience - better. Try to extend your writing expertise. Offer to work on other user-support materials such as training, whitepapers, demos, help, and so on, wherever you can add value to the product. Apply your tricks of the trade to other aspects of the product and tell a consistent story. This leads to the next point … Because you have oversight into many different aspects of the product or software, you are a also a natural to drive and standardize the product terminology in the guides, and also the user interface, and supporting processes.
- There’s a close connection between the technical writer and the stakeholders that represent the product and user’s concerns. Your job is to make sure feedback received in each iteration is also integrated and improvement is attained. Help fellow team members learn about what you do and can do through holding the necessary workshops.
- To conclude…. The agile manifesto says … Individuals and interactions over processes and tools Working software over comprehensive documentation Customer collaboration over contract negotiationResponding to change over following a plan Whether you buy into this whole heartedly or not, as a technical writer in this kind of environment, you need to recognize the importance of collaboration, and creating usable, workable software – and documentation. So embrace the work and be a minimalist and give them what they need, clear, usable, quality documentation.
- References