Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
Agile documentation
Search
Soenke Ruempler
May 05, 2013
Programming
0
500
Agile documentation
Soenke Ruempler
May 05, 2013
Tweet
Share
More Decks by Soenke Ruempler
See All by Soenke Ruempler
Software migration strategies
s0enke
2
590
Make it SOLID. Software Architecture for System Administrators
s0enke
1
130
Agile documentation
s0enke
1
380
Other Decks in Programming
See All in Programming
パスキーのすべて / 20250324 iddance Lesson.5
kuralab
0
140
AI Coding Agent Enablement - エージェントを自走させよう
yukukotani
11
3.2k
Coding Experience Cpp vs Csharp - meetup app osaka@9
harukasao
0
540
snacks.nvim内のセットアップ不要なプラグインを紹介 / introduce_snacks_nvim
uhooi
0
360
AtCoder Heuristic First-step Vol.1 講義スライド
terryu16
3
1.1k
20250326_生成AIによる_レビュー承認システムの実現.pdf
takahiromatsui
17
6k
The Weight of Data: Rethinking Cloud-Native Systems for the Age of AI
hollycummins
0
210
Return of the Full-Stack Developer
simas
PRO
1
330
ノーコードツールの裏側につきまとう「20分岐」との戦い
oguemon
0
110
PsySHから紐解くREPLの仕組み
muno92
PRO
1
530
php-fpm がリクエスト処理する仕組みを追う / Tracing-How-php-fpm-Handles-Requests
shin1x1
5
880
ミリしらMCP勉強会
watany
4
620
Featured
See All Featured
Designing for humans not robots
tammielis
251
25k
CoffeeScript is Beautiful & I Never Want to Write Plain JavaScript Again
sstephenson
160
15k
The Pragmatic Product Professional
lauravandoore
33
6.5k
Music & Morning Musume
bryan
46
6.4k
実際に使うSQLの書き方 徹底解説 / pgcon21j-tutorial
soudai
177
52k
Fashionably flexible responsive web design (full day workshop)
malarkey
407
66k
Making the Leap to Tech Lead
cromwellryan
133
9.2k
Visualizing Your Data: Incorporating Mongo into Loggly Infrastructure
mongodb
45
9.5k
Why You Should Never Use an ORM
jnunemaker
PRO
55
9.3k
Art, The Web, and Tiny UX
lynnandtonic
298
20k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
251
21k
We Have a Design System, Now What?
morganepeng
51
7.5k
Transcript
Agile Documentation PHP Unconference EU, 2013-05-05 Soenke Ruempler
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/
About Jimdo • WYSIWYG Website creator in 12 languages •
currently 8 million registrations • ~150 employees in Offices in Hamburg, San Fransisco, Shanghai, Tokyo
We are hiring!
Agenda - What to expect? • What can be documented
in software engineering and IT operations • Documentation antipatterns • Documentation patterns • Agile documentation to the extreme!
None
Rules • Listen • Ask whenever you want • Think
• Discuss - it's a highly controversial topic!
What can be documented in Software Development and Operations?
Domain knowledge
Requirements knowledge
Code / API Documentation
High level architectural diagrams
Experience reports
Application specific knowledge
Test results
Processes (Not handled in this talk)
Antipatterns
Outdated documentation
Documentation not known / not found / not read
Documentation not written (?)
Too much documentation
Documentation of discussions, not stable states
Wrong focus, does not document intent
WTF???? Intention? Why is it an "extreme geloet"? https://github.com/s0enke/dropr/blob/master/classes/Client/Peer/HttpUpload.php#L101
"Tests are enough documentation" (?)
Documentation for the sake of documentation
We like enterprise conventions for documents!
None
Patterns and Criteria for successful Documentation
Document results, not discussions
http://www.agilemodeling.com/essays/agileDocumentation.htm
Information proximity
http://heather.sh/wp-content/uploads/2013/02/Neat-Whiteboard-Diagram.jpg
None
Single sourcing
http://www.agilemodeling.com/essays/singleSourceInformation.htm
http://plantuml.sourceforge.net/index.html
http://www.stack.nl/~dimitri/doxygen/
None
<img src="http://yuml.me/diagram/scruffy/class/[Wages]^-[Salaried], [Wages]^-[Contractor]" >
Also document the "why"
In order to <rationale> As a <role> I want <what>
User story!
"In order to ..."
Prefer executable specs over static documentation
None
Value of documentation vs. costs of documentation
Business value low high Total cost of ownership low high
Wikis Executable High level feature / behavior specs (e. g. cucumber) Static documents Unit tests
None
And in the devops world? (Some examples)
rspec for configuration management
puppet-rspec Aha! Rationale! But Why? But Why?
cucumber-nagios
Ecosystem documentaion as code!
Rationale / Business value Executable Specification of the feature
Rationale / Business value Executable Specification of the feature Monitors:
Working Jimdo website, Login, Upload to webserver, Background-Upload to S3, and S3 ;-)
Living documentation
Single source information! \o/
Never outdated! \o/
Fast feedback \o/
Business value, Intention and rationale are clear. \o/
None
?
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"