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
520
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
初学者でも今すぐできる、Claude Codeの生産性を10倍上げるTips
s4yuba
16
12k
Python型ヒント完全ガイド 初心者でも分かる、現代的で実践的な使い方
mickey_kubo
1
130
Quand Symfony, ApiPlatform, OpenAI et LangChain s'allient pour exploiter vos PDF : de la théorie à la production…
ahmedbhs123
0
200
プロダクト志向なエンジニアがもう一歩先の価値を目指すために意識したこと
nealle
0
130
すべてのコンテキストを、 ユーザー価値に変える
applism118
3
1.3k
0626 Findy Product Manager LT Night_高田スライド_speaker deck用
mana_takada
0
180
Google Agent Development Kit でLINE Botを作ってみた
ymd65536
2
260
なぜ適用するか、移行して理解するClean Architecture 〜構造を超えて設計を継承する〜 / Why Apply, Migrate and Understand Clean Architecture - Inherit Design Beyond Structure
seike460
PRO
3
780
GPUを計算資源として使おう!
primenumber
1
150
PHPで始める振る舞い駆動開発(Behaviour-Driven Development)
ohmori_yusuke
2
400
iOS 26にアップデートすると実機でのHot Reloadができない?
umigishiaoi
0
130
Rubyでやりたい駆動開発 / Ruby driven development
chobishiba
1
740
Featured
See All Featured
Put a Button on it: Removing Barriers to Going Fast.
kastner
60
3.9k
Code Review Best Practice
trishagee
69
19k
CSS Pre-Processors: Stylus, Less & Sass
bermonpainter
357
30k
Six Lessons from altMBA
skipperchong
28
3.9k
Code Reviewing Like a Champion
maltzj
524
40k
Speed Design
sergeychernyshev
32
1k
Let's Do A Bunch of Simple Stuff to Make Websites Faster
chriscoyier
507
140k
The Power of CSS Pseudo Elements
geoffreycrofte
77
5.9k
Why Our Code Smells
bkeepers
PRO
336
57k
Into the Great Unknown - MozCon
thekraken
40
1.9k
Art, The Web, and Tiny UX
lynnandtonic
299
21k
KATA
mclloyd
30
14k
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"