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
330
Agile documentation
Soenke Ruempler
May 14, 2013
Tweet
Share
More Decks by Soenke Ruempler
See All by Soenke Ruempler
Software migration strategies
s0enke
2
500
Make it SOLID. Software Architecture for System Administrators
s0enke
1
130
Agile documentation
s0enke
0
460
Other Decks in Programming
See All in Programming
AWS初心者ってどうやってAWSを学ぶ?〜アプリエンジニアがやってよかったアーキテクチャ学習方法〜
yamanashi_ren01
0
190
CSC307 Lecture 05
javiergs
PRO
0
210
実用的かつリーズナブルな 「Azure × Gemini × LINE」~キャラクターBot 実装ライブデモ~
tomodo_ysys
1
170
コード生成を伴うLLMエージェント - 2024.07.18 Tokyo AI
smiyawaki0820
11
4.1k
CSC307 Lecture 13
javiergs
PRO
0
150
はしめてのプログラミングとロボット制御
watawatavoltage
0
290
DDDを志して3年経ったら「DDDの皮を被ったクリーンアーキテクチャ」になった話【デブサミ2024夏】
texmeijin
1
620
Introduction of Happy Eyeballs Version 2 (RFC8305) to the Socket library
coe401_
1
220
さきがけから振り返るアーキテクチャ刷新 / Reflecting on the Architectural Renewal from the Vanguard
nrslib
2
780
最近追加した型の紹介とその振り返り
aki19035vc
0
180
なぜ宣言的 UI は壊れにくいのか / Why declarative UI is less fragile
uenitty
29
13k
初心者がおさえておきたいAWS CDKのベストプラクティス 2024
konokenj
15
7.3k
Featured
See All Featured
Happy Clients
brianwarren
94
6.6k
StorybookのUI Testing Handbookを読んだ
zakiyama
15
4.9k
Docker and Python
trallard
37
2.9k
Building Adaptive Systems
keathley
34
2k
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
kevinliebholz
12
3.8k
10 Git Anti Patterns You Should be Aware of
lemiorhan
652
58k
Code Review Best Practice
trishagee
58
16k
A better future with KSS
kneath
231
17k
Clear Off the Table
cherdarchuk
89
320k
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
26
1.6k
Helping Users Find Their Own Way: Creating Modern Search Experiences
danielanewman
26
2.1k
5 minutes of I Can Smell Your CMS
philhawksworth
200
19k
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"