Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

How can documentation become inherently Agile?

1,103 views

Published on

How can you foster a culture that gets your developers excited about documentation? How can you foster a culture that gets your developers excited about pleasing their customers?

Documentation is still the most important thing developers continually respond as most affecting their decision making. Frankly caring about documentation shows you care about the developer, whether external or internal. Yet, documentation is constantly pushed to the wayside, aligning that idea with Waterfall and top-down development. How do you then foster a culture that gets your developers excited to create documentation? And as an extension, how do you get your developers excited about pleasing their customers?

Start out by automating what you can and then creating a process. Documentation is something that requires discipline. It’s up to your team to identify what interruptions are constantly being pointed to as excuses for not completing the documentation. Then, you can put an investment into your documentation, looking to first solve and reduce those interruptions, making documentation the way you address repeated issues and make your customers more autonomous.

Documentation is actually particularly important to the Scrum process, where "documented" is part of the definition of "Done." Documentation can also be a good team-building exercise as it invites everyone to take ownership of their own piece. It also keeps everyone cognizant of keeping the code itself simple and self-explanatory. And it's especially important for team communication and collaboration as, with microservices, containers and the like, our developers gain autonomy, but there's a struggle to work out loud so you know what everyone else is doing.

Finally, someone should be in charge of managing the documentation -- someone with a tech background but some marketing savviness -- to curate it all, helping to make sure it's there and that it tells a clear story that's easy to search through, but that also supports the overall business proposition.

This talk was first given at AgiNext 2017, London.
http://2017.aginext.io/
Images compliments of New Old Stock http://nos.twnsnd.co/

Published in: Software
  • Be the first to comment

How can documentation become inherently Agile?

  1. 1. H O W C A N D O C U M E N T A T I O N B E C O M E I N H E R E N T L Y A G I L E ? J E N N I F E R R I G G I N S @ J K R I G G I N S # A G I N E X T
  2. 2. H O W C A N Y O U F O S T E R A C U L T U R E T H A T G E T S Y O U R D E V E L O P E R S E X C I T E D A B O U T D O C U M E N T A T I O N ?
  3. 3. H O W C A N Y O U F O S T E R A C U L T U R E T H A T G E T S Y O U R D E V E L O P E R S E X C I T E D A B O U T P L E A S I N G T H E I R C U S T O M E R S ?
  4. 4. G A M E P L A N • Why are docs important? What makes good documentation? What makes it un-agile? • Waterfall to Agile transformation • Kanban RICE transformation • Scrum transformation • Automation, Continuous Documentation, Doc-First • Who’s in charge?
  5. 5. W H Y D O N ’ T Y O U T H I N K D O C S A R E A G I L E ?
  6. 6. W H Y A R E D O C S R E J E C T E D ? Feels like Waterfall, old school Never enough time Boring, a pain Lack of ownership Hot Potato Syndrome
  7. 7. “ I ’ V E S E E N F E W T E A M S W H O A R E A C T U A L L Y A G I L E , W H E R E E V E R Y O N E I S A B L E T O W O R K O N S T U F F A T T H E S A M E T I M E , W H E R E Y O U G E T U P A N D D O W N I N T H A T C I R C U L A R E F F E C T . I T D O E S T E N D T O B E A S E R I E S O F M I N I - W A T E R F A L L S . ” @ A G I L E D O C
  8. 8. “ A P I D E S I G N - F I R S T I S I N H E R E N T L Y N O T A G I L E . W E D E S I G N T H E W H O L E T H I N G A N D T H E N T H R O W T H E W H O L E T H I N G O V E R [ D E C L A R I N G ] ‘ B E T H E R E C I P I E N T S O F O U R W I S D O M ’ . ” @ M A N P
  9. 9. “ T H I S I S T H E G O O D A N D B A D S I D E O F A G I L E A U T O N O M Y … I N T H E E N D , I F I T ’ S D O N E W I T H O U T C O N T R O L , W E W I L L H A V E M A N Y M A N Y M I C R O S E R V I C E S T H A T D O N ’ T S P E A K T H E S A M E L A N G U A G E A N D I T W I L L C O S T A B U N C H O F M O N E Y . ” @ A P I H A N D Y M A N
  10. 10. “ T H E P I E C E A B O U T I T B E I N G ‘ T H E N U M B E R - O N E T H I N G P E O P L E W A N T ’ I S N ’ T R E G I S T E R I N G A T M O S T C O M P A N I E S I S E R V E . N O T A L L O F T H E M A R E I N T H E O P E N - S O U R C E S P A C E , W H E R E D O C U M E N T A T I O N T R U L Y S E L L S T H E P R O D U C T , B U T M O S T O F M Y C L I E N T S T H I N K A B O U T D O C U M E N T A T I O N T O O L A T E A N D R E S I S T P A Y I N G R E S P E C T A B L E R A T E S W H E N T H E Y F I N D T H E R A R E C O M B I N A T I O N O F D E V E L O P E R S K I L L S A N D T E C H N I C A L W R I T I N G T A L E N T . ” @ S Y N E R G I S T E C H
  11. 11. W H Y D O Y O U N E E D D O C U M E N T A T I O N ?
  12. 12. W H Y D O C S ? • Cuts customer support • Affects decision making • For API consumers, most important thing • Shows you care about DX • Internal efficiency
  13. 13. W H Y D O C S ? • Only way to unite developer autonomous world of containers, microservices and the like • Documentation = simpler code • Allows you to prototype, write spec • True collaboration = truly agile
  14. 14. D O C U M E N T A T I O N S H O U L D F I T I N T H E A G I L E W O R L D “ B E C A U S E Y O U H A V E T H E A B I L I T Y T O M O D I F Y T H E T H I N G T H A T D R I V E S T H E W H O L E P R O C E S S A T A L M O S T E V E R Y S T A G E O F D E V E L O P M E N T . A N D T H E M O D I F I C A T I O N S C A N A F F E C T I N A C O N T R O L L E D W A Y A L L O F T H E A R T I F A C T S T H A T A R E D O W N S T R E A M O F I T . ” @ F E H G U Y
  15. 15. W H A T M A K E S F O R G O O D D O C U M E N T A T I O N ?
  16. 16. W H A T I S G O O D D O C U M E N T A T I O N ? • Simple, to the point • Personal, specific to user, major personas • Searchable • Continuous • Involves the consumer
  17. 17. “ I F I C A N ’ T D E S C R I B E I T A N D I ’ M W O R K I N G A R O U N D S O M E T H I N G I N T H E D O C U M E N T A T I O N , T H E N I N E E D T O F I X S O M E T H I N G I N T H E C O D E . ” @ G J T O R I K I A N
  18. 18. H O W W O R L D P A Y W E N T F R O M W A T E R F A L L T O A G I L E
  19. 19. W O R L D P A Y B E F O R E @ W O R L D P A Y _ G L O B A L Devs in four countries Frustrating APIs users struggled to use
  20. 20. P A T H F R O M W A T E R F A L L T O A G I L E @ C R O W H U R S T S T E L L A 1. Survey Customers 2. Work with customer service 3. Lean: What were wastes in process? 4. Gave two in-company workshops - User personas - Customer journey mapping 5. Gap Analysis — what were Stripe and Braintree doing?
  21. 21. L E A N C U S T O M E R J O U R N E Y M A P P I N G Where do they need docs? What kinds of docs do they want? What are their pain points? @ C R O W H U R S T S T E L L A
  22. 22. “ W E T H I N K T H A T I F A P R O D U C T I S D E V E L O P E D T H E R I G H T W A Y , U S E R S S H O U L D N ’ T R E A L L Y N E E D D O C U M E N T A T I O N , B U T I N O U R E X P E R I E N C E P E O P L E U S U A L L Y L O O K A T D O C U M E N T A T I O N W H E N T H E Y H A V E A P R O B L E M O R , A S D E V E L O P E R S , I S T H E T O O L T H E Y U S E T O W O R K O N A D A Y - T O - D A Y B A S I S T O I N T E G R A T E . S O W H A T W E D E C I D E D T O F O C U S O N W A S I N T E G R A T I O N D O C U M E N T A T I O N A N D F A Q T O S U P P O R T U S E R S W H E N T H E Y H A V E P R O B L E M S . ” " @ C R O W H U R S T S T E L L A
  23. 23. H O W S E N D G R I D T R A N S F O R M E D K A N B A N W I T H R I C E
  24. 24. S E N D G R I D B E F O R E @ S E N D G R I D Docs team went agile two years ago Two week sprints Huge docs debt Reactionary documentation Constantly updating priorities Needed to prioritize for biggest impact
  25. 25. Highest score, gets top building Prioritizes Kanban backlog Solves for urgencies Solves for size of project Your ability to get it DONE Transparency R I C E F O R M U L A = R E A C H X I M P A C T X C O N F I D E N C E D I V I D E D B Y E F F O R T @ I N T E R C O M
  26. 26. @ M B E R N I E R S E N D G R I D ’ S R I C E T W E A K S Whole implementation took 30 minutes RICE = Reach X Impact X Confidence X Business Imperative X Due Date divided by Effort
  27. 27. Docs team +50% velocity in one month OS team 2x velocity in one week No more constant updating priorities A spreadsheet calculates it all for them 3 lines in Excel > backlog in JIRA S E N D G R I D ’ S R E S U L T S @ M B E R N I E R
  28. 28. “When something doesn’t feel right? Talk about it.” Open-Source & Docs Teams: “Everything can be agile.” Efficiencies + frustrations = center stage Backlog transparency S E N D G R I D ’ S R E S U L T S @ M B E R N I E R
  29. 29. S C R U M : H O W C A N D O C S + S P R I N T S E V E N W O R K ?
  30. 30. S H O U L D D O C S = D O N E ?
  31. 31. I F D O C S = S C R U M T H E N … @ A G I L E D O C Start early. Sit side by side. Continually updated. Can’t be shipped if not documented. Check in with UX + DX. It ain’t for everybody…
  32. 32. " I F O N L Y T H E D E S I G N A T E D T E C H N I C A L W R I T E R C A N P R O D U C E T H E D O C U M E N T A T I O N , Y O U ’ R E A S I N G L E - F U N C T I O N A L T E A M . B E A R I N M I N D T H A T A D D I N G A N A D D I T I O N A L W R I T E R W O N ' T M A K E Y O U S E M I - F U N C T I O N A L , B E C A U S E D O C U M E N T A T I O N C A N ' T C O M P L E T E U N T I L T E S T I N G C O M P L E T E S , S O A D D I N G A N O T H E R W R I T E R W I L L G I V E Y O U M O R E M A N P O W E R , B U T I T W O N ' T C H A N G E T H E I N H E R E N T P R O B L E M T H A T S O F T W A R E D E V E L O P M E N T I S A L I N E A R P R O C E S S . " @ A G I L E D O C
  33. 33. C A N Y O U R S C R U M T E A M … ? Question 1: Can Anyone other than the tech writer complete the documentation tasks? @ A G I L E D O C
  34. 34. C A N Y O U R S C R U M T E A M … ? Question 2: What portion of the docs can be finished quickly by tech writer? @ A G I L E D O C
  35. 35. C A N Y O U R S C R U M T E A M … ? Question 2: What portion of the docs can be finished quickly by tech writer? >75% for single functional teams >50% for semi-functional teams @ A G I L E D O C
  36. 36. C A N Y O U R S C R U M T E A M … ? Question 3: Is the documentation consistently high quality? @ A G I L E D O C
  37. 37. C A N Y O U R S C R U M T E A M … ? Question 4: Is there only one deliverable? @ A G I L E D O C
  38. 38. C A N Y O U R S C R U M T E A M … ? Question 5: Do you have a docs guide, standards and templates? @ A G I L E D O C
  39. 39. C A N Y O U R S C R U M T E A M … ? Question 6: Does your team enhance your documentation? @ A G I L E D O C
  40. 40. C A N Y O U R S C R U M T E A M … ? If YES to most of these, you can move toward DOCS = DONE. @ A G I L E D O C
  41. 41. “ D O C U M E N T A T I O N S H O U L D N O T B E T H E P A R T O F T H E S O F T W A R E D E V E L O P M E N T P R O C E S S T H A T C A U S E S Y O U T O N O T G E T Y O U R D E F I N I T I O N O F D O N E . ” @ A G I L E D O C
  42. 42. S O , H O W C A N D O C S J I V E W I T H A G I L E ?
  43. 43. D O C S C U R A T O R & S T Y L E G U I D E
  44. 44. H O W D O Y O U A U T O M A T E D O C U M E N T A T I O N P R O C E S S E S ?
  45. 45. C R E A T E A D U P L I C A T A B L E P R O C E S S , T H E N A U T O M A T E I T S O Y O U D O N ’ T M I S S A N Y T H I N G
  46. 46. W H E R E T O A U T O M A T E @ C H R I S C H I N C H Markdown-Spellcheck Doc style guide + quick reference list Code example testing Screenshot automation of successful tests
  47. 47. “ O N E O F T H E T H I N G S T H A T W E Q U I C K L Y R E A L I Z E D W E C O U L D N ’ T D O W A S C R E A T E D O C U M E N T A T I O N T H A T L I V E D A P A R T F R O M O U R C O D E . I T H A D T O L I V E D I R E C T L Y A L O N G S I D E O U R C O D E O R I T ’ D B E I M M E D I A T E L Y O U T O F D A T E . ” @ R V I S O T C K Y
  48. 48. D O C U M E N T A T I O N = D I S C I P L I N E @ J K R I G G I N S
  49. 49. T H E P I E C E S O F T H E C H A N G I N G D E V E L O P M E N T C Y C L E L I K E C O N T A I N E R S A N D M I C R O S E R V I C E S T H A T M A K E D O C U M E N T A T I O N L E S S L I K E L Y M E A N S I T ’ S A C T U A L L Y M O R E N E C E S S A R Y . B U T T H E S E C A N A L L L E A D T O E V E N B E T T E R , C O - O W N E D D O C U M E N T A T I O N . @ J K R I G G I N S
  50. 50. A G I L E D O C U M E N T A T I O N = B E T T E R T E A M S Everyone takes charge of own piece. Everyone wants simple, explanatory code (not self-explanatory.) Individual developer can still be creative, but has to communicate. @ J K R I G G I N S
  51. 51. W H A T S T E P S W I L L Y O U T A K E ? J E N N I F E R R I G G I N S @ J K R I G G I N S # A G I N E X T T H A N K S T O N E W O L D S T O C K F O R I M A G E S

×