Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Speaker Deck
PRO
Sign in
Sign up for free
Agile documentation
Soenke Ruempler
May 05, 2013
Programming
0
340
Agile documentation
Soenke Ruempler
May 05, 2013
Tweet
Share
More Decks by Soenke Ruempler
See All by Soenke Ruempler
Software migration strategies
s0enke
2
410
Make it SOLID. Software Architecture for System Administrators
s0enke
1
120
Agile documentation
s0enke
1
210
Other Decks in Programming
See All in Programming
YATA: collaborative documents and how to make them fast
horusiath
1
170
SAM × Dockerでサーバーレス開発が超捗った話
yu_yukk_y
1
440
ちょっとつよい足トラ
logilabo
0
420
WindowsコンテナDojo:第6回 Red Hat OpenShift入門
oniak3ibm
PRO
0
180
パスワードに関する最近の動向
kenchan0130
1
340
一口目から美味しいReactのスルメ本🦑
taro28
2
700
「困りごと」から始める個人開発
ikumatadokoro
4
270
アジャイルで始める データ分析基盤構築
nagano
1
930
Untangling Coroutine Testing (Droidcon Berlin 2022)
zsmb
2
500
MLOps勉強会_リアルタイムトラフィックのサーバレスMLOps基盤_20220810
strsaito
1
460
ベストプラクティス・ドリフト
sssssssssssshhhhhhhhhh
1
220
モデルの定義に基づくバリデーションを実現するためのpydantic入門
daikikatsuragawa
0
120
Featured
See All Featured
A Modern Web Designer's Workflow
chriscoyier
689
180k
Cheating the UX When There Is Nothing More to Optimize - PixelPioneers
stephaniewalter
269
12k
A designer walks into a library…
pauljervisheath
197
16k
Pencils Down: Stop Designing & Start Developing
hursman
113
9.9k
Build The Right Thing And Hit Your Dates
maggiecrowley
19
1.2k
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_i
25
15k
GitHub's CSS Performance
jonrohan
1020
420k
The Pragmatic Product Professional
lauravandoore
19
3.1k
Art Directing for the Web. Five minutes with CSS Template Areas
malarkey
196
9.5k
Creatively Recalculating Your Daily Design Routine
revolveconf
207
10k
The World Runs on Bad Software
bkeepers
PRO
57
5.4k
Typedesign – Prime Four
hannesfritz
34
1.4k
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"