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 14, 2013
Programming
1
370
Agile documentation
Soenke Ruempler
May 14, 2013
Tweet
Share
More Decks by Soenke Ruempler
See All by Soenke Ruempler
Software migration strategies
s0enke
2
540
Make it SOLID. Software Architecture for System Administrators
s0enke
1
130
Agile documentation
s0enke
0
490
Other Decks in Programming
See All in Programming
Semantic Kernelのネイティブプラグインで知識拡張をしてみる
tomokusaba
0
180
これが俺の”自分戦略” プロセスを楽しんでいこう! - Developers CAREER Boost 2024
niftycorp
PRO
0
190
PHPUnitしか使ってこなかった 一般PHPerがPestに乗り換えた実録
mashirou1234
0
130
生成AIでGitHubソースコード取得して仕様書を作成
shukob
0
330
DevFest Tokyo 2025 - Flutter のアプリアーキテクチャ現在地点
wasabeef
5
900
Recoilを剥がしている話
kirik
5
6.6k
Webエンジニア主体のモバイルチームの 生産性を高く保つためにやったこと
igreenwood
0
330
103 Early Hints
sugi_0000
1
230
20年もののレガシープロダクトに 0からPHPStanを入れるまで / phpcon2024
hirobe1999
0
440
あれやってみてー駆動から成長を加速させる / areyattemite-driven
nashiusagi
1
200
42 best practices for Symfony, a decade later
tucksaun
1
180
命名をリントする
chiroruxx
1
390
Featured
See All Featured
YesSQL, Process and Tooling at Scale
rocio
169
14k
Let's Do A Bunch of Simple Stuff to Make Websites Faster
chriscoyier
507
140k
Code Reviewing Like a Champion
maltzj
520
39k
Build your cross-platform service in a week with App Engine
jlugia
229
18k
The Art of Delivering Value - GDevCon NA Keynote
reverentgeek
8
1.2k
4 Signs Your Business is Dying
shpigford
181
21k
Principles of Awesome APIs and How to Build Them.
keavy
126
17k
How GitHub (no longer) Works
holman
311
140k
The Illustrated Children's Guide to Kubernetes
chrisshort
48
48k
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
127
18k
A designer walks into a library…
pauljervisheath
204
24k
GraphQLとの向き合い方2022年版
quramy
44
13k
Transcript
Agile Documentation PHP Usergroup Hamburg 2013-05-14 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"