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
スタックチャン家庭用アシスタントへの道
kanekoh
0
130
AIでテストプロセス自動化に挑戦する
sakatakazunori
1
590
サイバーエージェントグループのSRE10年の歩みとAI時代の生存戦略
shotatsuge
4
1.2k
低レイヤソフトウェア技術者が YouTuberとして食っていこうとした話
sat
PRO
6
5.7k
データ駆動経営の道しるべ:プロダクト開発指標の戦略的活用法
ham0215
2
190
ゼロから始めるSREの事業貢献 - 生成AI時代のSRE成長戦略と実践 / Starting SRE from Day One
shinyorke
PRO
0
180
Maintainer Meetupで「生の声」を聞く ~講演だけじゃないKubeCon
logica0419
0
140
How Do I Contact Jetblue Airlines® Reservation Number: Fast Support Guide
thejetblueairhelpsupport
0
200
毎晩の 負荷試験自動実行による効果
recruitengineers
PRO
5
200
Introduction to Sansan, inc / Sansan Global Development Center, Inc.
sansan33
PRO
0
2.7k
PHPでResult型やってみよう
higaki_program
0
130
AWS 怖い話 WAF編 @fillz_noh #AWSStartup #AWSStartup_Kansai
fillznoh
0
140
Featured
See All Featured
It's Worth the Effort
3n
185
28k
4 Signs Your Business is Dying
shpigford
184
22k
Mobile First: as difficult as doing things right
swwweet
223
9.7k
The Language of Interfaces
destraynor
158
25k
How To Stay Up To Date on Web Technology
chriscoyier
790
250k
Improving Core Web Vitals using Speculation Rules API
sergeychernyshev
18
1k
Why Our Code Smells
bkeepers
PRO
337
57k
The Pragmatic Product Professional
lauravandoore
35
6.8k
The Straight Up "How To Draw Better" Workshop
denniskardys
235
140k
Thoughts on Productivity
jonyablonski
69
4.7k
Building Flexible Design Systems
yeseniaperezcruz
328
39k
The Illustrated Children's Guide to Kubernetes
chrisshort
48
50k
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