Executable Documentation

More code, less wiki.

Transcript

1. EXECUTABLE DOCUMENTATION MORE CODE, LESS WIKI. Michael V. O’Brien @michaelvobrien 2012/02/02
2. TEAM
3. DESIGNER “What is redis?”
4. ROOKIE “I want all my tests to pass green. Today!”
5. VETERAN “Updated. Now there are errors! I just want to get my work done!”
6. CONFIGURATION
7. WHERE? WIKIS
8. WHERE? BLOGS
9. Wiki
10. WHERE? E-MAILS
11. WHERE? COWORKERS
12. COMMUNICATION
13. Coworker Change Project Update Wiki Send E-mail
14. E-mail
15. You Update Project Read E-mail Read Wiki Attempt Update Talk Coworker Coworker Coworker Instant Message Page 2 Page 3 Page 1
16. 0% 25% 50% 75% 100% Typical Ideal Wiki Code
17. AS A USER...
18. I DON’T WANT TO CONFIGURE MY SYSTEM
19. I WANT TOOL & DATA SEPARATION
20. I WANT UNDERSTANDABLE CODE
21. I WANT TO USE HOMEBREW
22. ARCHITECTURE
23. Tool Packages (Homebrew) Recipe & Data
24. IMPORTANT THINGS
25. IMPORTANT IDEMPOTENT
26. IMPORTANT PRINT STATUS MESSAGES
27. IMPORTANT DO MOST COMMON CHECKS
28. HELPERS
29. PACKAGE NO OPERATIONS MODE USE HOMEBREW INSTALL & UPGRADE
30. package(name)
31. FILE NO OPERATIONS MODE PRINT DIFF OF THE FILE REPLACE IF DIFFERENT
32. file(path, content)
33. SCRIPT NO OPERATIONS MODE PRINT COMMANDS TO RUN OUTPUT STDOUT/STDERR
34. script(description, should_run, commands)
35. SHELL NO OPERATIONS MODE PRINT COMMANDS TO RUN OUTPUT STDOUT/STDERR EXIT STATUS
36. sh_exitstatus(command) sh_out(command) SAFE NOT SAFE
37. FORK IT https://github.com/michaelvobrien/ct