Agile documentation

Transcript

1. Agile Documentation PHP Usergroup Hamburg 2013-05-14 Soenke Ruempler
2. About me "Chief Trolling Officer" at Jimdo Passionate about the web, open source, agile software development and knowledge management (and everything combined) Twitter: @s0enke Blog: http://ruempler.eu/
3. About Jimdo • WYSIWYG Website creator in 12 languages • currently 8 million registrations • ~150 employees in Offices in Hamburg, San Fransisco, Shanghai, Tokyo
4. We are hiring!
5. Agenda - What to expect? • What can be documented in software engineering and IT operations • Documentation antipatterns • Documentation patterns • Agile documentation to the extreme!
7. Rules • Listen • Ask whenever you want • Think • Discuss - it's a highly controversial topic!
8. What can be documented in Software Development and Operations?
9. Domain knowledge
10. Requirements knowledge
11. Code / API Documentation
12. High level architectural diagrams
13. Experience reports
14. Application specific knowledge
15. Test results
16. Processes (Not handled in this talk)
17. Antipatterns
18. Outdated documentation
19. Documentation not known / not found / not read
20. Documentation not written (?)
21. Too much documentation
22. Documentation of discussions, not stable states
23. Wrong focus, does not document intent
24. WTF???? Intention? Why is it an "extreme geloet"? https://github.com/s0enke/dropr/blob/master/classes/Client/Peer/HttpUpload.php#L101
25. "Tests are enough documentation" (?)
26. Documentation for the sake of documentation
27. We like enterprise conventions for documents!
29. Patterns and Criteria for successful Documentation
30. Document results, not discussions
31. http://www.agilemodeling.com/essays/agileDocumentation.htm
32. Information proximity
33. http://heather.sh/wp-content/uploads/2013/02/Neat-Whiteboard-Diagram.jpg
35. Single sourcing
36. http://www.agilemodeling.com/essays/singleSourceInformation.htm
37. http://plantuml.sourceforge.net/index.html
38. http://www.stack.nl/~dimitri/doxygen/
40. <img src="http://yuml.me/diagram/scruffy/class/[Wages]^-[Salaried], [Wages]^-[Contractor]" >
41. Also document the "why"
42. In order to <rationale> As a <role> I want <what>
43. User story!
44. "In order to ..."
45. Prefer executable specs over static documentation
47. Value of documentation vs. costs of documentation
48. Business value low high Total cost of ownership low high Wikis Executable High level feature / behavior specs (e. g. cucumber) Static documents Unit tests
50. And in the devops world? (Some examples)
51. rspec for configuration management
52. puppet-rspec Aha! Rationale! But Why? But Why?
53. cucumber-nagios
54. Ecosystem documentaion as code!
55. Rationale / Business value Executable Specification of the feature
56. Rationale / Business value Executable Specification of the feature Monitors: Working Jimdo website, Login, Upload to webserver, Background-Upload to S3, and S3 ;-)
57. Living documentation
58. Single source information! \o/
59. Never outdated! \o/
60. Fast feedback \o/
61. Business value, Intention and rationale are clear. \o/
63. ?
64. Links and Literature • My diploma thesis • Scott Ambler on Agile Documentation • Specification by Example • cucumber-nagios • "Software Engineering Rationale: Wissen über Software erheben und erhalten"