Move Fast and Document Things

Strategies for writing internal docs at fast-moving organizations. Email me for the speaker notes!

Transcript

1. M O V E FA S T
   A N D D O C U M E N T T H I N G S
   S T R A T E G I E S F O R W R I T I N G I N T E R N A L D O C S A T FA S T- M O V I N G O R G A N I Z A T I O N S
   R U T H I E B E N D O R
   @ U N R U T H L E S S
   

   View Slide

2. @ U N R U T H L E S S
   

   View Slide

3. @ U N R U T H L E S S
   E X T E R N A L T E C H N I C A L D O C S
   

   View Slide

4. @ U N R U T H L E S S
   E X T E R N A L T E C H N I C A L D O C S
   A P I R E F E R E N C E ! H O W - T O G U I D E S ! S A M P L E A P P S !
   FA Q S ! D E V E L O P E R D O C S ! S D K S !
   

   View Slide

5. @ U N R U T H L E S S
   credit: https://www.flickr.com/photos/skylarprimm/9385954331
   I N T E R N A L T E C H N I C A L D O C S
   

   View Slide

6. @ U N R U T H L E S S
   credit: https://www.flickr.com/photos/skylarprimm/9385954331
   I N T E R N A L T E C H N I C A L D O C S
   R E A D M E S ! U P T I M E D O C S ! W I K I PA G E S !
   E M A I L S ! P O S T- I T S !
   C O L L E A G U E ’ S
   B R A I N !
   

   View Slide

7. T H E M AT E R I A L S W E C R E AT E F O R O U R C O L L E A G U E S
   — A N D F O R O U R F U T U R E S E LV E S ! —
   T H AT E N A B L E U S T O B U I L D U P O N O U R W O R K .
   @ U N R U T H L E S S
   I N T E R N A L T E C H N I C A L D O C S :
   

   View Slide

8. @ U N R U T H L E S S
   

   View Slide

9. @ U N R U T H L E S S
   

   View Slide

10. @ U N R U T H L E S S
    

    View Slide

11. @ U N R U T H L E S S
    

    View Slide

12. – S L O W - M O V I N G N O N P R O F I T
    “We care about internal technical docs because
    they help us make our software last as long as possible.”
    @ U N R U T H L E S S
    

    View Slide

13. @ U N R U T H L E S S
    A N D N O W,
    F O R S O M E T H I N G
    C O M P L E T E LY
    D I F F E R E N T
    

    View Slide

14. @ U N R U T H L E S S
    

    View Slide

15. – A G E N C Y
    “We care about internal technical docs because
    … actually, we don’t.”
    @ U N R U T H L E S S
    

    View Slide

16. @ U N R U T H L E S S
    

    View Slide

17. – S TA R T U P
    “We care about internal technical docs because
    they help us onboard new staff.”
    @ U N R U T H L E S S
    

    View Slide

18. C O M PA N Y
    C O M PA N Y
    @ U N R U T H L E S S
    

    View Slide

19. @ U N R U T H L E S S
    

    View Slide

20. B O S S
    B O S S
    B O S S < B O S S @ C O M PA N Y. C O M >
    C O M PA N Y
    @ U N R U T H L E S S
    

    View Slide

21. B O S S < B O S S @ C O M PA N Y. C O M >
    C O M PA N Y
    C O M PA N Y
    C O M PA N Y
    @ U N R U T H L E S S
    

    View Slide

22. C O M PA N Y P R O D U C T
    P R O D U C T
    @ U N R U T H L E S S
    

    View Slide

23. C O M PA N Y P R O D U C T
    P R O D U C T
    @ U N R U T H L E S S
    # S TA R T U P LY F E
    

    View Slide

24. $ git checkout 56a4e5c08
    Note: checking out '56a4e5c08'.
    You are in 'detached HEAD' state…
    $ _
    @ U N R U T H L E S S
    

    View Slide

25. H O W T O W R I T E I N T E R N A L D O C S
    AT FA S T- M O V I N G O R G A N I Z AT I O N S
    @ U N R U T H L E S S
    in four simple steps
    

    View Slide

26. F I G U R E O U T W H AT ’ S B R O K E N .
    S T E P 1 :
    @ U N R U T H L E S S
    

    View Slide

27. ✓ 100% Pre-Commit Code Review!
    ✓ Continuous Integration!
    ✓ Monitoring!
    ✓ No deploys on Fridays past 4pm!
    @ U N R U T H L E S S
    T H I N G S T H AT W E R E N O T B R O K E N
    

    View Slide

28. ✓ Amazing Colleagues!
    @ U N R U T H L E S S
    T H I N G S T H AT W E R E N O T B R O K E N
    

    View Slide

29. T H I N G S T H AT W E R E B R O K E N
    • Belief that internal technical docs depreciate in value too quickly
    R U T H I E B E N D O R
    @ U N R U T H L E S S
    

    View Slide

30. T H I N G S T H AT W E R E B R O K E N
    • Belief that internal technical docs depreciate in value too quickly
    • Presumption of homogenous technical backgrounds
    • Presumption of institutional knowledge
    R U T H I E B E N D O R
    @ U N R U T H L E S S
    

    View Slide

31. T H I N G S T H AT W E R E B R O K E N
    • Belief that internal technical docs depreciate in value too quickly
    • Presumption of homogenous technical backgrounds
    • Presumption of institutional knowledge
    • No unambiguous“right” way to write internal docs
    @ U N R U T H L E S S
    

    View Slide

32. F I G U R E O U T W H AT ’ S B R O K E N .
    S T E P 1 :
    @ U N R U T H L E S S
    

    View Slide

33. F I G U R E O U T W H Y Y O U R O R G A N I Z AT I O N
    W I L L C A R E A B O U T F I X I N G I T.
    S T E P 2 :
    @ U N R U T H L E S S
    

    View Slide

34. – S L O W - M O V I N G N O N P R O F I T
    “We care about internal technical docs because
    they help us make our software last as long as possible.”
    @ U N R U T H L E S S
    

    View Slide

35. – S TA R T U P
    “We care about internal technical docs because
    they help us onboard new staff.”
    @ U N R U T H L E S S
    

    View Slide

36. – S TA R T U P
    “We care about internal technical docs because
    they increase bus factor.”
    @ U N R U T H L E S S
    

    View Slide

37. – S TA R T U P
    “We care about internal technical docs because
    they increase bus factor.”
    @ U N R U T H L E S S
    

    View Slide

38. – S TA R T U P
    “We care about internal technical docs because
    ________.”
    @ U N R U T H L E S S
    

    View Slide

39. – S TA R T U P
    “We care about internal technical docs
    because we value learning from each other.”
    @ U N R U T H L E S S
    

    View Slide

40. F I G U R E O U T W H Y Y O U R O R G A N I Z AT I O N
    W I L L C A R E A B O U T F I X I N G I T.
    S T E P 2 :
    @ U N R U T H L E S S
    

    View Slide

41. C O U C H Y O U R S O L U T I O N S I N T H E
    O R G A N I Z AT I O N ’ S VA L U E S .
    S T E P 3 :
    @ U N R U T H L E S S
    

    View Slide

42. AT E V E RY I N F L E C T I O N P O I N T,
    R E E VA L U AT E , R I N S E , R E P E AT.
    S T E P 4 :
    @ U N R U T H L E S S
    

    View Slide

43. T H A N K S !
    C O M E S A Y H I !
    I ’ M R U T H I E B E N D O R .
    S L A C K + T W I T T E R : @ U N R U T H L E S S
    E M A I L : R U T H I E @ U N R U T H L E S S . C O M
    

    View Slide