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
いまからでも遅くない!SSL/TLS証明書超入門(It's not too late to start! SSL/TLS Certificates: The Absolute Beginner's Guide)
norimuraz
0
240
BI ツールはもういらない?Amazon RedShift & MCP Server で試みる新しいデータ分析アプローチ
cdataj
0
160
"プロポーザルってなんか怖そう"という境界を超えてみた@TSUDOI by giftee Tech #1
shilo113
0
190
技育祭2025【秋】 企業ピッチ/登壇資料(高橋 悟生)
hacobu
PRO
0
100
研究開発部メンバーの働き⽅ / Sansan R&D Profile
sansan33
PRO
3
20k
Claude Codeを駆使した初めてのiOSアプリ開発 ~ゼロから3週間でグローバルハッカソンで入賞するまで~
oikon48
8
3.2k
「れきちず」のこれまでとこれから - 誰にでもわかりやすい歴史地図を目指して / FOSS4G 2025 Japan
hjmkth
1
310
HR Force における DWH の併用事例 ~ サービス基盤としての BigQuery / 分析基盤としての Snowflake ~@Cross Data Platforms Meetup #2「BigQueryと愉快な仲間たち」
ryo_suzuki
0
220
OCI Network Firewall 概要
oracle4engineer
PRO
2
7.9k
フレームワークを意識させないワークショップづくり
keigosuda
0
190
プレーリーカードを活用しよう❗❗デジタル名刺交換からはじまるイベント会場交流のススメ
tsukaman
0
160
プロポーザルのコツ ~ Kaigi on Rails 2025 初参加で3名の登壇を実現 ~
naro143
1
240
Featured
See All Featured
Improving Core Web Vitals using Speculation Rules API
sergeychernyshev
20
1.2k
The Art of Delivering Value - GDevCon NA Keynote
reverentgeek
16
1.7k
Building Better People: How to give real-time feedback that sticks.
wjessup
369
20k
Chrome DevTools: State of the Union 2024 - Debugging React & Beyond
addyosmani
8
910
Building Adaptive Systems
keathley
44
2.8k
We Have a Design System, Now What?
morganepeng
53
7.8k
Evolution of real-time – Irina Nazarova, EuRuKo, 2024
irinanazarova
9
980
The Cost Of JavaScript in 2023
addyosmani
55
9k
The Invisible Side of Design
smashingmag
302
51k
KATA
mclloyd
32
15k
Embracing the Ebb and Flow
colly
88
4.8k
JavaScript: Past, Present, and Future - NDC Porto 2020
reverentgeek
52
5.6k
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