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
Executable Documentation
Search
Michael O'Brien
May 02, 2012
Technology
5
230
Executable Documentation
More code, less wiki.
Michael O'Brien
May 02, 2012
Tweet
Share
Other Decks in Technology
See All in Technology
カンファレンスに託児サポートがあるということ / Having Childcare Support at Conferences
nobu09
0
130
いまさら聞けない ABテスト入門
skmr2348
1
210
Azure SynapseからAzure Databricksへ 移行してわかった新時代のコスト問題!?
databricksjapan
0
150
「AI駆動PO」を考えてみる - 作る速さから価値のスループットへ:検査・適応で未来を開発 / AI-driven product owner. scrummat2025
yosuke_nagai
4
650
生成AIを活用したZennの取り組み事例
ryosukeigarashi
0
210
Access-what? why and how, A11Y for All - Nordic.js 2025
gdomiciano
1
120
フルカイテン株式会社 エンジニア向け採用資料
fullkaiten
0
9.1k
小学4年生夏休みの自由研究「ぼくと Copilot エージェント」
taichinakamura
0
500
Escaping_the_Kraken_-_October_2025.pdf
mdalmijn
0
150
o11yで育てる、強い内製開発組織
_awache
3
120
ユニットテストに対する考え方の変遷 / Everyone should watch his live coding
mdstoy
0
130
Git in Team
kawaguti
PRO
2
150
Featured
See All Featured
Thoughts on Productivity
jonyablonski
70
4.9k
Automating Front-end Workflow
addyosmani
1371
200k
GraphQLの誤解/rethinking-graphql
sonatard
73
11k
Build The Right Thing And Hit Your Dates
maggiecrowley
37
2.9k
Easily Structure & Communicate Ideas using Wireframe
afnizarnur
194
16k
Helping Users Find Their Own Way: Creating Modern Search Experiences
danielanewman
30
2.9k
Visualizing Your Data: Incorporating Mongo into Loggly Infrastructure
mongodb
48
9.7k
Practical Orchestrator
shlominoach
190
11k
Faster Mobile Websites
deanohume
310
31k
Documentation Writing (for coders)
carmenintech
75
5k
Site-Speed That Sticks
csswizardry
11
880
Making the Leap to Tech Lead
cromwellryan
135
9.5k
Transcript
EXECUTABLE DOCUMENTATION MORE CODE, LESS WIKI. Michael V. O’Brien @michaelvobrien
2012/02/02
TEAM
DESIGNER “What is redis?”
ROOKIE “I want all my tests to pass green. Today!”
VETERAN “Updated. Now there are errors! I just want to
get my work done!”
CONFIGURATION
WHERE? WIKIS
WHERE? BLOGS
Wiki
WHERE? E-MAILS
WHERE? COWORKERS
COMMUNICATION
Coworker Change Project Update Wiki Send E-mail
E-mail
You Update Project Read E-mail Read Wiki Attempt Update Talk
Coworker Coworker Coworker Instant Message Page 2 Page 3 Page 1
0% 25% 50% 75% 100% Typical Ideal Wiki Code
AS A USER...
I DON’T WANT TO CONFIGURE MY SYSTEM
I WANT TOOL & DATA SEPARATION
I WANT UNDERSTANDABLE CODE
I WANT TO USE HOMEBREW
ARCHITECTURE
Tool Packages (Homebrew) Recipe & Data
IMPORTANT THINGS
IMPORTANT IDEMPOTENT
IMPORTANT PRINT STATUS MESSAGES
IMPORTANT DO MOST COMMON CHECKS
HELPERS
PACKAGE NO OPERATIONS MODE USE HOMEBREW INSTALL & UPGRADE
package(name)
FILE NO OPERATIONS MODE PRINT DIFF OF THE FILE REPLACE
IF DIFFERENT
file(path, content)
SCRIPT NO OPERATIONS MODE PRINT COMMANDS TO RUN OUTPUT STDOUT/STDERR
script(description, should_run, commands)
SHELL NO OPERATIONS MODE PRINT COMMANDS TO RUN OUTPUT STDOUT/STDERR
EXIT STATUS
sh_exitstatus(command) sh_out(command) SAFE NOT SAFE
FORK IT https://github.com/michaelvobrien/ct