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