Today’s Agile Documentation
3 likes•1,784 views
This document discusses agile documentation practices based on a survey of 57 Symantec information developers. Some key findings include: - Most information developers have less than one year of agile experience and see benefits of agile like improved schedules and delivering value. - Frequent deployment and reviews have improved documentation quality by focusing on smaller chunks of work. Remote collaboration remains a challenge. - Agile practices like daily stand-ups, estimating tasks, and transparent reporting increase motivation and accountability for documentation work. - Strategies like cross-training, defining "done", tailoring stories to the organization, and using technology help information developers adapt to agile.
Today’s Agile Documentation
- 1. Today’s agile documentation oday s ag e docu e tat o Megan Leney, Senior Information Developer Symantec Corporation July 22, 2009
- 2. About me •Agile enthusiast, C tifi d S A il th i t Certified Scrum M tMaster •Sr. Information Developer, Symantec Insert Photo •Previously worked for VeriSign and Apple Here •Lead the integration of VeriSign's documentation team into the developer-run agile scrum process process. •Presented on agile documentation at 2008 LavaCon Prof. Development Conference •Member, Sili M b Silicon V ll STC Ch t Valley Chapter
- 3. Agenda g 1 Overview of current agile and trends 2 The 2009 Symantec Agile Documentation Survey 3 What Symantec information developers are saying 4 What the agile trends mean to writers
- 4. Overview of agile and current trends
- 5. What Agile is not… g • A new idea • A“ “cookie cutter” solution f all problems ki tt ” l ti for ll bl • A detailed plan for every contingency 5
- 6. What Agile is about… g • Iterative development • H d work Hard k • Transparency 6
- 7. Key agile stakeholders y g • Product owner –C b a P d t M Can be Product Manager or P j t M Project Manager – Figures out the WHAT with customers – Decides what comes off the backlog to get something else done • Scrum master – Often a Dev manager – Works with the team to figure out HOW things g done g g get • Team – Self-organized g – Creates value 7
- 8. Agile vocabulary g y • Scrum. A scrum is a 15-30 minute daily check-in meeting in which you report p g y p progress and any blocking issues. y g • Sprint (or Iteration). An iterative development cycle. The length of the cycle is predetermined by the team (usually 2-4 weeks). D i each sprint, th t k ) During h i t the team produces a d demonstrative unit. • Handoff meeting A meeting at the end of an iteration during meeting. which the team demonstrates a unit of work to the product owner. • Retrospective. A meeting during which the team reflects on what went well during the current iteration, and what they can improve on next iteration. Usually takes place right after the handoff meeting. 8
- 9. Agile vocabulary g y • User Story. A simple story that reflects a customer requirement. Stories are p q placed on the backlog and g prioritized during the sprint planning phase. User story format: As a <role> I want <something> (optional) so th t <some justification> that j tifi ti Some examples include: – A an IT administrator, I want i As d i i instructions on upgrading f i di from version i A to version B. – As a CTO, I want to protect my servers in case of a natural disaster, such as a flood or earthquake. 9
- 10. Agile vocabulary g y • Task. A unit of work that can be completed in 1-2 days. • Acceptance criteria. The criteria that determine whether a criteria story is complete. 10
- 13. Agile then and now g 2001 (the year Agile Manifesto signed) ( y g g ) 2009 Integrating agile team practices Deploying agile to the enterprise Product owner committed to team/responsible Product owner not too involved in process for ROI Scrum master is in charge of the team Scrum master coaches and facilitates self (command and control) organization Teams develop products for customers Teams partner with customers to create value Individual “superheroes” I di id l “ h ” Teamwork T k
- 14. Recent trends in agile and what they mean to information developers p Agile trend g Information development challenge p g More frequent deployment of increasingly • Managing our workload complex products • Delivering quality documentation • Getting the information we need Increased geographic distribution • Communicating remotely Increased accountability and transparency • Exposing issues so they are easier to solve • Getting what we need from product Closer relationships with customers management • Creating a better user experience
- 15. Big ugly problems Insert Photo are solved by Here peoples’ brains, not processes. You Dr. Dan Rawsthorne, Danube Technologies, Inc. don t don’t need big processes.
- 16. The 2009 Symantec Agile Documentation Survey
- 17. Global survey: 57 Symantec info dev p professionals
- 18. Agile experience g p Years of experience 18% more than 3 years 52% less than one year 30% 1-3 years
- 19. (Non-agile writers) How would switching to agile impact you? g g p y
- 20. Percentage of non-agile writers who think agile would help in the following areas: g p g
- 21. Percentage of non-agile writers who think these agile practices would help g p p
- 22. To transition to agile, information developers need to understand… p Agile/scrum benefits • S t i bl schedule Sustainable h d l • Delivering documentation value Agile/scrum practices • I Importance of daily scrum meetings t f d il ti • Continuous improvement (retrospectives) • Handoff demos each iteration 22
- 23. How helpful do agile writers find agile? g
- 24. How helpful do agile writers ? p g
- 25. How helpful do agile writers find agile/scrum? g
- 26. How helpful do agile writers find agile/scrum? g
- 27. How helpful do agile writers find agile? g
- 28. How else does agile help information developers? p • Strong support for the documentation process • A better sense of your due dates • Focus on a few features and cover them more in depth • F l lik you’re part of th team, more in th l Feel like ’ t f the t i the loop • Higher visibility • E i t set expectations Easier to t t ti 28
- 29. How helpful do agile writers find these agile practices? g p
- 30. How helpful do agile writers find these agile practices? g p
- 31. How helpful do agile writers find these agile practices? g p
- 32. How helpful do agile writers find these agile practices? g p
- 33. How helpful do agile writers find these agile practices? g p
- 34. What other agile/scrum practices help Information Developers? p p • Detailed scheduling ensures developers don’t take on too much • Using the same tools as developers to track progress • Estimating documentation tasks 34
- 35. What Symantec information developers are saying d l i
- 36. Undergo agile training; talk to other information developers who work in an agile environment; understand what agile can and cannot do for information developers. Anonymous survey response 36
- 37. Make an effort to integrate with the Dev and QA processes, instead of embedding yourself in a defined ‘InfoDev’ process flow. Be flexible and adaptable. Anonymous survey response 37
- 38. Information developers must educate the engineering team about how the Tech Pubs team will work with them in the agile method. method Anonymous survey response 38
- 39. What the agile trends mean to writers g 1 Agile and frequent deployment 2 Increased geographic distribution 3 Accountability and transparency 4 Leveraging customer relationships
- 41. What is more frequent deployment? q p y • Time boxing (small increments of work in a short time) • D il meetings where you agree on t d ’ reality Daily ti h today’s lit • Iterations create demonstrative units –N l No longer “ t ti ll ship-able” “potentially hi bl ” – Demonstrative does not mean “sell-able” – You need at least one additional iteration to ship the p p product 41
- 42. How has more frequent deployment affected documentation quality? q y
- 43. Agile documentation reviews g • Iterative reviews are very informal – Perform daily reviews, or as often as needed reviews – Target one SME to review the text – Send as little as one paragraph p g p – Expect immediate turnaround - one day max! • Formal reviews – Hold at least one end-to-end review – Create a documentation review story • Add t k f developers and QA t review th d tasks for d l d to i the documentation t ti • Add tasks for incorporating comments 43
- 44. One risk of agile is that focus is shifted from ‘the forest’ to ‘the trees.’ Anonymous survey response 44
- 45. How have more frequent reviews impacted documentation quality? p q y
- 46. How have more frequent reviews impacted documentation quality? p q y
- 47. How have more frequent reviews impacted documentation quality? p q y
- 48. How does more frequent deployment affect ability to manage workload? y g
- 49. Strategy #1 Know that the whole team is responsible for the backlog p g Cross-training helps team members be more efficient For example, train your developers in writing error messages They make a first pass, reduce the time it takes you to write from scratch 49
- 50. Strategy #2 Put everything you do on the backlog g Reasons to put everything on the backlog • Y get credit f everything you d You t dit for thi do • The team sees what is left out of the build • It’ easier t plan th next ti It’s i to l the t time around d 50
- 51. Strategy #3 Spend story points wisely and communicate availability y • Think about how you want to spend your story points – Spend 1/3 of your points on documentation only stories documentation-only – Spend 2/3 on features • Estimate how long you spend in team meetings and training activities – These are important activities that make you more efficient – Deduct meeting and training time from resource availability 51
- 52. Strategy #4 Create a definition of “done” that works for you y • Think about how you want to work – Complete feature docs in the same iteration? – Complete rough drafts in the same iteration? – Deliver draft documentation in an iteration + 1 schedule? – Deliver polished chapters in an iteration +2 schedule? • Communicate what you need to accomplish the acceptance criteria – Instant reviews – Features complete the first week of iteration • Set expectations on exactly what you can deliver • No scope creep: once you’ve defined “done ” stick with it! you ve done, 52
- 54. What kind of team(s) do you work with?
- 55. How much do you gain agile benefits working with remote teams? g
- 56. How much do you gain agile benefits working with remote teams? g
- 57. How much do you gain agile benefits working with remote teams? g
- 58. How much do you gain agile benefits working with remote teams? g
- 59. How much do you gain agile benefits working with remote teams? g
- 60. How often do remote SMEs communicate about incidents, issues, and features? , ,
- 61. Strategy #1 Get to know your distributed teammates • Team members are not roles, they are people • R Respect their ti t th i time, b t ask th but k them questions about th ti b t themselves l – Get on calls early and talk while waiting for people to join – Start off talking about their career and the company 61
- 62. Strategy #1 Get to know your distributed teammates Ask if they’d be willing to share photographs China development team Mountain View Installer doc team Andy Wang; Fred Wen; Megan Leney and Elizabeth Carlassare Sophie Yin and William Li 62
- 63. Strategy #1 Get to know your distributed teammates Responses from teammates about exchanging photographs: Hey Willi H William, This is awesome! It’s always good to know your fellow members by face especially when we are working in scrum :) Hi Elizabeth/Megan, Pretty cool! Thanks for sharing this picture to us. It is very nice to see you, so vivid! And I am sure we can think of you clearer during the next conf call. g 63
- 64. Form a good working relationship, and maintain it by being accessible and responsive. Anonymous survey response 64
- 65. Do your homework and target …questions and requests…to the most appropriate person - respect their time. Anonymous survey response 65
- 66. My t M team mates are not as t t young today as when we started working together so t t d ki t th calls at 3 AM are no longer appreciated. i t d Anonymous survey response 66
- 67. Strategy #2 Tailor stories to the way y your organization works g Two schools of thought: 1.Make the t i 1 M k th stories self-contained so th t teams can lf t i d that t accomplish the story tasks independently of each other. 2.Force 2 Force the story to go across teams so that they have to talk to each other 67
- 68. Strategy #3 Use technology gy gy • Share your desktop using Live Meeting and co-develop content with a remote SME • Be sure the same servers and systems are available to all team members • Use Instant messenger • Some teams have the luxury of web cams, Halo conference rooms 68
- 69. Strategy #4 Be p gy persistent • Find out who you need to talk to • C ll and i t t message often Call d instant ft • Ask a lot of questions 69
- 70. How effectively do remote SMEs communicate important information? p
- 71. Communicate as often as p possible. Anonymous survey response 71
- 73. Information Developers …(need) to estimate…to the ( ) feature level -- and when working on multiple features, g p , things can get ‘off schedule’ very q y quickly. y Anonymous survey response 73
- 74. The (scrum) process it lf Th ( ) itself provides all of the accountability and transparency anyone could dt ld possibly want. Anonymous survey response y y p 74
- 75. Advantages of accountability and transparency p y • Understanding documentation tasks • S l i i Solving issues b f before th get out of hand they t t f h d • The whole team is responsible for user stories • I Increased motivation to complete stories d ti ti t l t t i – For developers—they’re forced to complete reviews on time – For writers—keeps us on track easier to meet deadlines writers keeps track, 75
- 76. Agile…makes it easier to A il k i t understand when schedules might be at risk. i ht b t i k Anonymous survey response 76
- 77. How well do you understand your documentation tasks?
- 78. How much motivation does the daily reporting of status give you to complete stories?
- 79. How often do you experience team swarm? Team “swarm” is energetically working with scrum teammates to complete stories Bee images from: Winterville Elementary School Media Center http://wintervillemc.googlepages.com/home
- 80. ( (What) seems to enhance ) "accountability & transparency" is when I complete a more p challenging piece, I PDF it and send it to concerned parties to p see if … (it’s) in the ballpark with p their expectations. Anonymous survey response 80
- 81. Communicate expectations. C i i …Don't agree to something before you investigate, that b f i ti t th t way you can always complete things you commit to do. thi it t d Anonymous survey response 81
- 83. Why work closely with product management? g • Product managers are the voice of the customer • P d t managers are good at b ildi customer Product d t building t relationships • Customers deserve to know what you are doing; they are paying for it 83
- 84. How easy is it to create documentation that meets customers’ needs?
- 85. How easy is it to adapt to customers’ changing requirements? g g q
- 86. How well does your product owner convey changes in customer requirements? g q
- 87. The agile model comes with built-in flexibility...If a feature y is urgently required by a customer…(you) factor it (y ) into the (iteration) planning. Anonymous survey response 87
- 88. The more contact with field personnel who directly deal with customers and with customers, customers themselves, the better. better You need to understand your audience. Anonymous survey response 88
- 89. Add value to not just the documentation but the product as a whole. Anonymous survey response 89
- 90. Q&A
- 91. Summary and S d Conclusions
- 92. Delivering quality with more frequent deployment p y • Work closely with the team to get information • H ld reviews often; send d Hold i ft d documentation t j t a f t ti to just few t team members • Put all tasks for formal reviews on the backlog 92
- 93. Communicating with remote team members • Get to know your teammates • A k questions, rather th expecting them t communicate Ask ti th than ti th to i t information • Use technology to facilitate meetings and the exchange of information 93
- 94. Using accountability and transparency to your advantage p y y g • Make it a priority to attend all scrum meetings • W k energetically (“ Work ti ll (“swarm”) with t ”) ith teammates to complete t t l t stories • Set expectations so the team knows what you can commit to expectations, 94
- 95. Leveraging close relationships with customers • Work closely with the product owner to understand customer needs • Let the product owner know what you need from them to deliver value 95
- 96. Thank Y ! Th k You! Megan Leney g _ y@ y [email protected] Copyright © 2008 Symantec Corporation. All rights reserved. Symantec and the Symantec Logo are trademarks or registered trademarks of Symantec Corporation or its affiliates in the U.S. and other countries. Other names may be trademarks of their respective owners. This document is provided for informational purposes only and is not intended as advertising. All warranties relating to the information in this document, either express or implied, are disclaimed to the maximum extent allowed by law. The information in this document is subject to change without notice.