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
COVESA VSSによる車両データモデルの標準化とAWS IoT FleetWiseの活用
osawa
1
280
未経験者・初心者に贈る!40分でわかるAndroidアプリ開発の今と大事なポイント
operando
5
480
品質視点から考える組織デザイン/Organizational Design from Quality
mii3king
0
200
企業の生成AIガバナンスにおけるエージェントとセキュリティ
lycorptech_jp
PRO
2
160
[ JAWS-UG 東京 CommunityBuilders Night #2 ]SlackとAmazon Q Developerで 運用効率化を模索する
sh_fk2
3
400
複数サービスを支えるマルチテナント型Batch MLプラットフォーム
lycorptech_jp
PRO
0
330
大「個人開発サービス」時代に僕たちはどう生きるか
sotarok
20
9.9k
人工衛星のファームウェアをRustで書く理由
koba789
15
7.8k
「どこから読む?」コードとカルチャーに最速で馴染むための実践ガイド
zozotech
PRO
0
320
Language Update: Java
skrb
2
290
「何となくテストする」を卒業するためにプロダクトが動く仕組みを理解しよう
kawabeaver
0
400
下手な強制、ダメ!絶対! 「ガードレール」を「檻」にさせない"ガバナンス"の取り方とは?
tsukaman
2
440
Featured
See All Featured
Side Projects
sachag
455
43k
Intergalactic Javascript Robots from Outer Space
tanoku
272
27k
GraphQLの誤解/rethinking-graphql
sonatard
72
11k
Six Lessons from altMBA
skipperchong
28
4k
Unsuck your backbone
ammeep
671
58k
Building a Scalable Design System with Sketch
lauravandoore
462
33k
Why Our Code Smells
bkeepers
PRO
339
57k
Chrome DevTools: State of the Union 2024 - Debugging React & Beyond
addyosmani
7
840
Facilitating Awesome Meetings
lara
55
6.5k
Fantastic passwords and where to find them - at NoRuKo
philnash
52
3.4k
Code Review Best Practice
trishagee
70
19k
Designing Experiences People Love
moore
142
24k
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