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
340
Agile documentation
Soenke Ruempler
May 14, 2013
Tweet
Share
More Decks by Soenke Ruempler
See All by Soenke Ruempler
Software migration strategies
s0enke
2
510
Make it SOLID. Software Architecture for System Administrators
s0enke
1
130
Agile documentation
s0enke
0
470
Other Decks in Programming
See All in Programming
Using Livebook to build and deploy internal tools @ ElixirConf 2024
hugobarauna
0
250
ECMAScript、Web標準の型はどう管理されているか / How ECMAScript and Web standards types are maintained
petamoriken
3
390
Ruby Parser progress report 2024
yui_knk
2
230
Understand the mechanism! Let's do screenshots tests of Compose Previews with various variations / 仕組みから理解する!Composeプレビューを様々なバリエーションでスクリーンショットテストしよう
sumio
3
860
2024 컴포즈 정원사
jisungbin
0
150
Google Sign-inの移行から始めるCredential Manager活用
clockvoid
0
420
大公開!iOS開発の悩みトップ5 〜iOSDC Japan 2024〜
ryunakayama
0
190
Desafios e Lições Aprendidas na Migração de Monólitos para Microsserviços em Java
jessilyneh
2
150
意外とフォントが大事だった話 / Font Issues on Internationalization
fumi23
0
110
Scala におけるコンパイラエラーとの付き合い方
chencmd
2
430
Go1.23で入った errorsパッケージの小さなアプデ
kuro_kurorrr
2
400
Architecture Decision Record (ADR)
nearme_tech
PRO
1
690
Featured
See All Featured
Fashionably flexible responsive web design (full day workshop)
malarkey
401
65k
[RailsConf 2023 Opening Keynote] The Magic of Rails
eileencodes
28
8.9k
Adopting Sorbet at Scale
ufuk
73
8.9k
Building Applications with DynamoDB
mza
90
6k
Navigating Team Friction
lara
183
13k
GraphQLの誤解/rethinking-graphql
sonatard
65
9.8k
Reflections from 52 weeks, 52 projects
jeffersonlam
346
20k
Building a Modern Day E-commerce SEO Strategy
aleyda
36
6.8k
Designing with Data
zakiwarfel
98
5k
Statistics for Hackers
jakevdp
794
220k
Fireside Chat
paigeccino
31
2.9k
Optimising Largest Contentful Paint
csswizardry
31
2.8k
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"