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
480
Agile documentation
Soenke Ruempler
May 05, 2013
Tweet
Share
More Decks by Soenke Ruempler
See All by Soenke Ruempler
Software migration strategies
s0enke
2
530
Make it SOLID. Software Architecture for System Administrators
s0enke
1
130
Agile documentation
s0enke
1
360
Other Decks in Programming
See All in Programming
PLoP 2024: The evolution of the microservice architecture pattern language
cer
PRO
0
1.6k
Googleのテストサイズを活用したテスト環境の構築
toms74209200
0
270
現場で役立つモデリング 超入門
masuda220
PRO
13
2.9k
Vue SFCのtemplateでTypeScriptの型を活用しよう
tsukkee
3
1.5k
AWS IaCの注目アップデート 2024年10月版
konokenj
3
3.1k
Kaigi on Rails 2024 - Rails APIモードのためのシンプルで効果的なCSRF対策 / kaigionrails-2024-csrf
corocn
5
3.4k
Amazon Neptuneで始めてみるグラフDB-OpenSearchによるグラフの全文検索-
satoshi256kbyte
4
330
のびしろを広げる巻き込まれ力:偶然を活かすキャリアの作り方/oso2024
takahashiikki
1
410
『ドメイン駆動設計をはじめよう』のモデリングアプローチ
masuda220
PRO
8
440
Why Spring Matters to Jakarta EE - and Vice Versa
ivargrimstad
0
980
Go言語でターミナルフレンドリーなAIコマンド、afaを作った/fukuokago20_afa
monochromegane
2
140
Vitest Browser Mode への期待 / Vitest Browser Mode
odanado
PRO
2
1.7k
Featured
See All Featured
[RailsConf 2023] Rails as a piece of cake
palkan
51
4.9k
GitHub's CSS Performance
jonrohan
1030
460k
Dealing with People You Can't Stand - Big Design 2015
cassininazir
364
22k
Building Your Own Lightsaber
phodgson
102
6k
Testing 201, or: Great Expectations
jmmastey
38
7k
Building a Scalable Design System with Sketch
lauravandoore
459
33k
Mobile First: as difficult as doing things right
swwweet
222
8.9k
Creating an realtime collaboration tool: Agile Flush - .NET Oxford
marcduiker
25
1.8k
The Language of Interfaces
destraynor
154
24k
The World Runs on Bad Software
bkeepers
PRO
65
11k
Understanding Cognitive Biases in Performance Measurement
bluesmoon
26
1.4k
Optimising Largest Contentful Paint
csswizardry
33
2.9k
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"