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
220
Executable Documentation
More code, less wiki.
Michael O'Brien
May 02, 2012
Tweet
Share
Other Decks in Technology
See All in Technology
LLMマルチエージェントのフローエンジニアリングを支えるLLM Ops
pharma_x_tech
3
690
SRE改善サイクルはチームを超えて - ダッシュボードを眺める会の取り組み/SRE improvement cycle across teams
aeonpeople
1
110
サプライチェーン攻撃に備える
ryunen344
0
510
プログラム検証入門
riru
6
1.2k
エムスリーエビデンス創出プロダクトチーム紹介資料 / Introduction of M3 Create Evidence Team
m3_engineering
0
1.3k
DuckDB雑紹介(1.1対応版)@DuckDB座談会
ktz
10
1.9k
学術機関におけるID連携とOpenID Connect
fujie
0
490
Kubernetesって何? -大規模なKubernetesを運用するKubernetes as a Serviceチームの話を添えて-
lycorptech_jp
PRO
12
4.1k
Developer Experienceを向上させる基盤づくりの取り組み事例集
coconala_engineer
0
170
DroidKaigi 2024 たすけて!ViewModel
mhidaka
6
1.2k
Oracle Base Database Service 技術詳細
oracle4engineer
PRO
5
46k
内製化を目指す事業会社が、システム開発会社と共に進める「開発生産性改善」の取り組み事例 #devsumi
yuwji
1
290
Featured
See All Featured
Pencils Down: Stop Designing & Start Developing
hursman
119
11k
The Cost Of JavaScript in 2023
addyosmani
42
5.7k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
227
52k
A Modern Web Designer's Workflow
chriscoyier
692
190k
How to Ace a Technical Interview
jacobian
274
23k
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
131
32k
The Art of Delivering Value - GDevCon NA Keynote
reverentgeek
2
60
What’s in a name? Adding method to the madness
productmarketing
PRO
21
3k
The Success of Rails: Ensuring Growth for the Next 100 Years
eileencodes
41
6.5k
Web Components: a chance to create the future
zenorocha
309
42k
Java REST API Framework Comparison - PWX 2021
mraible
PRO
27
7.4k
What the flash - Photography Introduction
edds
67
11k
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