Agile documentation

Transcript

1. 1.

   Agile Documentation PHP Usergroup Hamburg 2013-05-14 Soenke Ruempler

2. 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. 3.

   About Jimdo • WYSIWYG Website creator in 12 languages •

   currently 8 million registrations • ~150 employees in Offices in Hamburg, San Fransisco, Shanghai, Tokyo
4. 4.

   We are hiring!

5. 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. 6.

   None
7. 7.

   Rules • Listen • Ask whenever you want • Think

   • Discuss - it's a highly controversial topic!
8. 8.

   What can be documented in Software Development and Operations?

9. 9.

   Domain knowledge

10. 10.

    Requirements knowledge

11. 11.

    Code / API Documentation

12. 12.

    High level architectural diagrams

13. 13.

    Experience reports

14. 14.

    Application specific knowledge

15. 15.

    Test results

16. 16.

    Processes (Not handled in this talk)

17. 17.

    Antipatterns

18. 18.

    Outdated documentation

19. 19.

    Documentation not known / not found / not read

20. 20.

    Documentation not written (?)

21. 21.

    Too much documentation

22. 22.

    Documentation of discussions, not stable states

23. 23.

    Wrong focus, does not document intent

24. 24.

    WTF???? Intention? Why is it an "extreme geloet"? https://github.com/s0enke/dropr/blob/master/classes/Client/Peer/HttpUpload.php#L101

25. 25.

    "Tests are enough documentation" (?)

26. 26.

    Documentation for the sake of documentation

27. 27.

    We like enterprise conventions for documents!

28. 28.

    None
29. 29.

    Patterns and Criteria for successful Documentation

30. 30.

    Document results, not discussions

31. 31.

    http://www.agilemodeling.com/essays/agileDocumentation.htm

32. 32.

    Information proximity

33. 33.

    http://heather.sh/wp-content/uploads/2013/02/Neat-Whiteboard-Diagram.jpg

34. 34.

    None
35. 35.

    Single sourcing

36. 36.

    http://www.agilemodeling.com/essays/singleSourceInformation.htm

37. 37.

    http://plantuml.sourceforge.net/index.html

38. 38.

    http://www.stack.nl/~dimitri/doxygen/

39. 39.

    None
40. 40.

    <img src="http://yuml.me/diagram/scruffy/class/[Wages]^-[Salaried], [Wages]^-[Contractor]" >

41. 41.

    Also document the "why"

42. 42.

    In order to <rationale> As a <role> I want <what>

43. 43.

    User story!

44. 44.

    "In order to ..."

45. 45.

    Prefer executable specs over static documentation

46. 46.

    None
47. 47.

    Value of documentation vs. costs of documentation

48. 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. 49.

    None
50. 50.

    And in the devops world? (Some examples)

51. 51.

    rspec for configuration management

52. 52.

    puppet-rspec Aha! Rationale! But Why? But Why?

53. 53.

    cucumber-nagios

54. 54.

    Ecosystem documentaion as code!

55. 55.

    Rationale / Business value Executable Specification of the feature

56. 56.

    Rationale / Business value Executable Specification of the feature Monitors:

    Working Jimdo website, Login, Upload to webserver, Background-Upload to S3, and S3 ;-)
57. 57.

    Living documentation

58. 58.

    Single source information! \o/

59. 59.

    Never outdated! \o/

60. 60.

    Fast feedback \o/

61. 61.

    Business value, Intention and rationale are clear. \o/

62. 62.

    None
63. 63.

    ?

64. 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"