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
510
Agile documentation
Soenke Ruempler
May 05, 2013
Tweet
Share
More Decks by Soenke Ruempler
See All by Soenke Ruempler
Software migration strategies
s0enke
2
610
Make it SOLID. Software Architecture for System Administrators
s0enke
1
140
Agile documentation
s0enke
1
390
Other Decks in Programming
See All in Programming
Kotlin エンジニアへ送る:Swift 案件に参加させられる日に備えて~似てるけど色々違う Swift の仕様 / from Kotlin to Swift
lovee
1
260
#kanrk08 / 公開版 PicoRubyとマイコンでの自作トレーニング計測装置を用いたワークアウトの理想と現実
bash0c7
1
660
新メンバーも今日から大活躍!SREが支えるスケールし続ける組織のオンボーディング
honmarkhunt
1
240
Deep Dive into ~/.claude/projects
hiragram
10
2.1k
PHPでWebSocketサーバーを実装しよう2025
kubotak
0
240
High-Level Programming Languages in AI Era -Human Thought and Mind-
hayat01sh1da
PRO
0
640
Code as Context 〜 1にコードで 2にリンタ 34がなくて 5にルール? 〜
yodakeisuke
0
120
5つのアンチパターンから学ぶLT設計
narihara
1
130
Goで作る、開発・CI環境
sin392
0
180
GoのGenericsによるslice操作との付き合い方
syumai
3
700
AIコーディング道場勉強会#2 君(エンジニア)たちはどう生きるか
misakiotb
1
270
データの民主化を支える、透明性のあるデータ利活用への挑戦 2025-06-25 Database Engineering Meetup#7
y_ken
0
330
Featured
See All Featured
Site-Speed That Sticks
csswizardry
10
670
Performance Is Good for Brains [We Love Speed 2024]
tammyeverts
10
940
Typedesign – Prime Four
hannesfritz
42
2.7k
Rails Girls Zürich Keynote
gr2m
94
14k
[RailsConf 2023] Rails as a piece of cake
palkan
55
5.6k
The Web Performance Landscape in 2024 [PerfNow 2024]
tammyeverts
8
680
Build The Right Thing And Hit Your Dates
maggiecrowley
36
2.8k
YesSQL, Process and Tooling at Scale
rocio
173
14k
Designing Experiences People Love
moore
142
24k
How STYLIGHT went responsive
nonsquared
100
5.6k
StorybookのUI Testing Handbookを読んだ
zakiyama
30
5.8k
Into the Great Unknown - MozCon
thekraken
39
1.9k
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"