today’s agile documentation
DESCRIPTION
National Society for Technical Communication (STC) web seminar presented in July, 2009. Presents a 2009 survey of over 50 information developers at Symantec. Gives an overview of recent trends in Agile documentation. Provides tips on documenting with more frequent deployment, working with distributed teams, increased accountability and transparency, and leveraging customer relationships.TRANSCRIPT
Today’s agile documentation oday s ag e docu e tat oMegan Leney, Senior Information Developer
Symantec Corporation
July 22, 2009
About me
A il th i t C tifi d S M t
Insert Photo
•Agile enthusiast, Certified Scrum Master•Sr. Information Developer, Symantec•Previously worked for VeriSign and Apple Insert Photo
Here •Lead the integration of VeriSign's documentation team into the developer-run agile scrum processagile scrum process. •Presented on agile documentation at 2008 LavaCon Prof. Development Conference M b Sili V ll STC Ch t•Member, Silicon Valley STC Chapter
Agenda
Overview of current agile and trends
g
1
The 2009 Symantec Agile Documentation Survey
Overview of current agile and trends1
2
What Symantec information developers are saying
The 2009 Symantec Agile Documentation Survey2
3
What the agile trends mean to writers4
Overview of agile andOverview of agile and current trends
What Agile is not…g
• A new ideaA “ ki tt ” l ti f ll bl• A “cookie cutter” solution for all problems
• A detailed plan for every contingency
5
What Agile is about…g
• Iterative development H d k• Hard work
• Transparency
6
Key agile stakeholdersy g
• Product ownerC b P d t M P j t M– Can be a Product Manager or Project Manager
– Figures out the WHAT with customers Decides what comes off the backlog to get something else– 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 get doneg g g
• Team– Self-organized
7
g– Creates value
7
Agile vocabularyg y
• Scrum. A scrum is a 15-30 minute daily check-in meeting in which you report progress and any blocking issues. y p p g y g
• Sprint (or Iteration). An iterative development cycle. The length of the cycle is predetermined by the team (usually 2-4
k ) D i h i t th t dweeks). During each sprint, the team produces a demonstrative unit.
• Handoff meeting A meeting at the end of an iteration during• Handoff meeting. A meeting at the end of an iteration during 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 theimprove on next iteration. Usually takes place right after the handoff meeting.
8
Agile vocabularyg y
• User Story. A simple story that reflects a customer requirement. Stories are placed on the backlog and q p gprioritized during the sprint planning phase. User story format: As a <role> I want <something> (optional)
th t j tifi tiso that <some justification>Some examples include:
A IT d i i I i i di f i– As an IT administrator, I want instructions on upgrading from version 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
Agile vocabularyg y
• Task. A unit of work that can be completed in 1-2 days.• Acceptance criteria The criteria that determine whether a• Acceptance criteria. The criteria that determine whether a
story is complete.
10
Agile then and nowg
2001 (the year Agile Manifesto signed) 2009( y g g )
Integrating agile team practices Deploying agile to the enterprise
Product owner committed to team/responsibleProduct owner not too involved in process
Product owner committed to team/responsible for ROI
Scrum master is in charge of the team (command and control)
Scrum master coaches and facilitates self organization(command and control) organization
Teams develop products for customers Teams partner with customers to create value
I di id l “ h ” T kIndividual “superheroes” Teamwork
Recent trends in agile and what they mean to information developersp
Agile trend Information development challengeg p g
More frequent deployment of increasingly complex products
• Managing our workload
• Delivering quality documentation
Increased geographic distribution• Getting the information we need
• Communicating remotely
Increased accountability and transparency • Exposing issues so they are easier to solve
Closer relationships with customers• Getting what we need from product
management
• Creating a better user experience
Insert Photo
Big ugly problems are solved byInsert Photo
Hereare solved by peoples’ brains,
Dr. Dan Rawsthorne,
not processes. You don’t need bigDanube Technologies, Inc. don t need big processes.
The 2009 SymantecThe 2009 Symantec Agile Documentation SSurvey
Global survey: 57 Symantec info dev professionalsp
Agile experienceg p
Years of experience
18%
Years of experience
52% less than one year
18% more than 3 years
one year30%
1-3 years
(Non-agile writers) How would switching to agile impact you?g g p y
Percentage of non-agile writers who think agile would help in the following areas:g p g
Percentage of non-agile writers who think these agile practices would helpg p p
To transition to agile, information developers need to understand…p
Agile/scrum benefitsS t i bl h d l• Sustainable schedule
• Delivering documentation value
Agile/scrum practicesI t f d il ti• Importance of daily scrum meetings
• Continuous improvement (retrospectives)• Handoff demos each iteration
22
How helpful do agile writers find agile?g
How helpful do agile writers ?p g
How helpful do agile writers find agile/scrum?g
How helpful do agile writers find agile/scrum?g
How helpful do agile writers find agile?g
How else does agile help information developers?p
• Strong support for the documentation process• A better sense of your due dates• A better sense of your due dates • Focus on a few features and cover them more in depth
F l lik ’ t f th t i th l• Feel like you’re part of the team, more in the loop• Higher visibility
E i t t t ti• Easier to set expectations
28
How helpful do agile writers find these agile practices? g p
How helpful do agile writers find these agile practices? g p
How helpful do agile writers find these agile practices? g p
How helpful do agile writers find these agile practices? g p
How helpful do agile writers find these agile practices? g p
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 tasksEstimating documentation tasks
34
What SymantecWhat Symantec information d l idevelopers are saying
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
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
Information developers mustInformation developers must educate the engineering team about how the Techteam about how the Tech Pubs team will work with them in the agile methodthem in the agile method.
Anonymous survey response
38
What the agile trends mean to writers
Agile and frequent deployment
g
1
Increased geographic distribution
Agile and frequent deployment1
2
Accountability and transparency
Increased geographic distribution2
3
Leveraging customer relationships4
Agile and frequentAgile and frequent deployment
What is more frequent deployment?q p y
• Time boxing (small increments of work in a short time)D il ti h t d ’ lit• Daily meetings where you agree on today’s reality
• Iterations create demonstrative unitsN l “ t ti ll hi bl ”– No longer “potentially ship-able”
– Demonstrative does not mean “sell-able”– You need at least one additional iteration to ship the productp p
4141
How has more frequent deployment affected documentation quality?q y
Agile documentation reviewsg
• Iterative reviews are very informalPerform daily reviews or as often as needed– Perform daily reviews, or as often as needed
– 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 d l d QA t i th d t ti• Add tasks for developers and QA to review the documentation• Add tasks for incorporating comments
4343
One risk of agile is that focus is shifted from ‘the forest’ to ‘the trees.’
Anonymous survey response
44
How have more frequent reviews impacted documentation quality?p q y
How have more frequent reviews impacted documentation quality?p q y
How have more frequent reviews impacted documentation quality?p q y
How does more frequent deployment affect ability to manage workload?y g
Strategy #1 Know that the whole team is responsible for the backlogp 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
4949
Strategy #2 Put everything you do on the backlogg
Reasons to put everything on the backlogY t dit f thi d• You get credit for everything you do
• The team sees what is left out of the buildIt’ i t l th t ti d• It’s easier to plan the next time around
5050
Strategy #3 Spend story points wisely and communicate availabilityy
• Think about how you want to spend your story pointsSpend 1/3 of your points on documentation only stories– Spend 1/3 of your points on documentation-only stories
– Spend 2/3 on features
• Estimate how long you spend in team meetings and trainingEstimate 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
5151
Strategy #4 Create a definition of “done” that works for youy
• Think about how you want to workComplete feature docs in the same iteration?– 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– 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!
52
• No scope creep: once you ve defined done, stick with it!
52
Increased geographicIncreased geographic distribution
What kind of team(s) do you work with?
How much do you gain agile benefits working with remote teams?g
How much do you gain agile benefits working with remote teams?g
How much do you gain agile benefits working with remote teams?g
How much do you gain agile benefits working with remote teams?g
How much do you gain agile benefits working with remote teams?g
How often do remote SMEs communicate about incidents, issues, and features?, ,
Strategy #1 Get to know your distributed teammates
• Team members are not roles, they are peopleR t th i ti b t k th ti b t th l• Respect their time, but ask them questions about themselves– Get on calls early and talk while waiting for people to join– Start off talking about their career and the companyStart off talking about their career and the company
6161
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 CarlassareAndy Wang; Fred Wen; Megan Leney and Elizabeth Carlassare
Sophie Yin and William Li
6262
Strategy #1 Get to know your distributed teammates
Responses from teammates about exchanging photographs:H WilliHey William,
This is awesome! It’s always good to know your fellow members by face especially whenyour 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.
63
g
63
Form a good working relationship, and maintain it by being accessible and responsive.
Anonymous survey response
64
Do your homework and targetDo your homework and target …questions and requests…to the most appropriate person - respectmost appropriate person - respect their time.
Anonymous survey response
65
M t t tMy team mates are not as young today as when we t t d ki t thstarted working together so
calls at 3 AM are no longer i t dappreciated.
Anonymous survey response
66
Strategy #2 Tailor stories to the way your organization worksy g
Two schools of thought: 1 M k th t i lf t i d th t t1.Make the stories self-contained so that teams can
accomplish the story tasks independently of each other. 2 Force the story to go across teams so that they have to talk2.Force the story to go across teams so that they have to talk
to each other
6767
Strategy #3 Use technologygy gy
• Share your desktop using Live Meeting and co-develop content with a remote SMEcontent 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
6868
Strategy #4 Be persistentgy p
• Find out who you need to talk to C ll d i t t ft• Call and instant message often
• Ask a lot of questions
6969
How effectively do remote SMEs communicate important information?p
Communicate as often as possible.p
Anonymous survey response
71
Accountability andAccountability and transparency
Information Developers …(need) to estimate…to the ( )feature level -- and when working on multiple features, g p ,things can get ‘off schedule’ very quickly.y q y
73
Anonymous survey response
Th ( ) it lfThe (scrum) process itself provides all of the accountability
d t ldand transparency anyone could possibly want.
Anonymous survey responsey y p
74
Advantages of accountability and transparencyp y
• Understanding documentation tasksS l i i b f th t t f h d• Solving issues before they get out of hand
• The whole team is responsible for user storiesI d ti ti t l t t i• Increased motivation to complete stories– For developers—they’re forced to complete reviews on time
For writers keeps us on track easier to meet deadlines– For writers—keeps us on track, easier to meet deadlines
7575
A il k it i tAgile…makes it easier to understand when schedules
i ht b t i kmight be at risk.Anonymous survey response
76
How well do you understand your documentation tasks?
How much motivation does the daily reporting of status give you to complete stories?stories?
How often do you experience team swarm?
Team “swarm” is energetically working withworking with scrum teammates to completecomplete stories
Bee images from: Winterville Elementary School Media Center http://wintervillemc.googlepages.com/home
(What) seems to enhance ( )"accountability & transparency" is when I complete a more pchallenging piece, I PDF it and send it to concerned parties to psee if … (it’s) in the ballpark with their expectations.p
Anonymous survey response
80
C i iCommunicate expectations. …Don't agree to something b f i ti t th tbefore you investigate, that way you can always complete thi it t dthings you commit to do.
Anonymous survey responseAnonymous survey response
81
Leveraging customerLeveraging customerrelationships
Why work closely with product management?g
• Product managers are the voice of the customerP d t d t b ildi t• Product managers are good at building customer relationships
• Customers deserve to know what you are doing; they areCustomers deserve to know what you are doing; they are paying for it
8383
How easy is it to create documentation that meets customers’ needs?
How easy is it to adapt to customers’ changing requirements?g g q
How well does your product owner convey changes in customer requirements?g q
The agile model comes with built-in flexibility...If a feature yis urgently required by a customer…(you) factor it (y )into the (iteration) planning.
Anonymous survey response
87
The more contact with fieldThe more contact with field personnel who directly deal with customers and withwith customers, and with customers themselves, the better You need tobetter. You need to understand your audience.
Anonymous survey response
88
Add value to not just the documentation but the product as a whole.
Anonymous survey response
89
Q & AQ & A
S dSummary andConclusions
Delivering quality with more frequent deploymentp y
• Work closely with the team to get informationH ld i ft d d t ti t j t f t• Hold reviews often; send documentation to just a few team members
• Put all tasks for formal reviews on the backlogPut all tasks for formal reviews on the backlog
9292
Communicating with remote team members
• Get to know your teammatesA k ti th th ti th t i t• Ask questions, rather than expecting them to communicate information
• Use technology to facilitate meetings and the exchange ofUse technology to facilitate meetings and the exchange of information
9393
Using accountability and transparency to your advantagep y y g
• Make it a priority to attend all scrum meetingsW k ti ll (“ ”) ith t t t l t• Work energetically (“swarm”) with teammates to complete stories
• Set expectations so the team knows what you can commit toSet expectations, so the team knows what you can commit to
9494
Leveraging close relationships with customers
• Work closely with the product owner to understand customer needsneeds
• Let the product owner know what you need from them to deliver value
9595
Th k Y !Thank You!
Megan [email protected] _ y@ y
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.