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
Zero Data Loss Autonomous Recovery Service サービス概要
oracle4engineer
PRO
1
5k
embedパッケージを深掘りする / Deep Dive into embed Package in Go
task4233
0
170
Storage Browser for Amazon S3を触ってみた + α
miura55
0
120
.NET AspireでAzure Functionsやクラウドリソースを統合する
tsubakimoto_s
0
170
20240513 - 框裡框外_文學院學生如何在AI世代安身立命 @ 淡江大學
dpys
0
640
信頼されるためにやったこと、 やらなかったこと。/What we did to be trusted, What we did not do.
bitkey
PRO
0
1.9k
シフトライトなテスト活動を適切に行うことで、無理な開発をせず、過剰にテストせず、顧客をビックリさせないプロダクトを作り上げているお話 #RSGT2025 / Shift Right
nihonbuson
3
1.9k
12 Days of OpenAIから読み解く、生成AI 2025年のトレンド
shunsukeono_am
0
1.2k
JAWS-UG20250116_iOSアプリエンジニアがAWSreInventに行ってきた(真面目編)
totokit4
0
120
知っててうれしい SQL について
greendrop
0
120
Git scrapingで始める継続的なデータ追跡 / Git Scraping
ohbarye
4
270
Copilotの力を実感!3ヶ月間の生成AI研修の試行錯誤&成功事例をご紹介。果たして得たものとは・・?
ktc_shiori
0
290
Featured
See All Featured
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
132
33k
A Modern Web Designer's Workflow
chriscoyier
693
190k
Cheating the UX When There Is Nothing More to Optimize - PixelPioneers
stephaniewalter
280
13k
Being A Developer After 40
akosma
89
590k
GitHub's CSS Performance
jonrohan
1030
460k
The Cult of Friendly URLs
andyhume
78
6.1k
Producing Creativity
orderedlist
PRO
343
39k
How GitHub (no longer) Works
holman
312
140k
Designing for Performance
lara
604
68k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
230
52k
Fireside Chat
paigeccino
34
3.1k
ReactJS: Keep Simple. Everything can be a component!
pedronauck
666
120k
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