Agile documentation

Agile documentation

9f40c41cec8ab0f4fd1e7900a69b1d3d?s=128

Soenke Ruempler

May 14, 2013
Tweet

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!
  6. None
  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!

  28. None
  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

  34. None
  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/

  39. None
  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

  46. None
  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
  49. None
  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/

  62. None
  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"