The legend of documentation

The great majority of programmers agree that documentation is useful but not that many will take the time to write it. If code is the real source of truth, why bother writing documents that might soon get outdated? In this talk I tell you my story on how documentation helped ease the integration of new colleagues, how it promoted knowledge sharing and how it helped preventing internal disagreements.

Transcript

1. @fmendes6
   

   View Slide

2. “The resistance to
   documentation among
   developers is well known
   and needs no emphasis.”
   - D.Herbsleb & D. Moitra, 

   Global Software Development, IEEE, 2001
   

   View Slide

3. Have you ever needed some
   form of information from
   someone that was
   unavailable?
   

   View Slide

4. What is this
   system?
   How does it
   work?
   Why was it
   created this
   way?
   

   View Slide

5. View Slide

6. Mar ‘18
   

   View Slide

7. A
   vailable

   Documentation
   

   View Slide

8. Detailed Jira tickets, user
   stories, regression suites,
   glossaries, etc.
   

   View Slide

9. Documentation

   Android team
   

   View Slide

10. View Slide

11. Problem 1
    Lack of knowledge 

    about the app
    

    View Slide

12. Filipe, can you look at ticket X?
    

    View Slide

13. Hum…suuuure!
    

    View Slide

14. …
    

    View Slide

15. Ask And Continue
    Do not Ask and Continue
    Quit
    

    View Slide

16. I’m sorry, can you please help me?
    

    View Slide

17. What if your colleagues 

    are unavailable?
    

    View Slide

18. A dependency is a 

    problem if it blocks you 

    from progressing
    

    View Slide

19. Wiki
    

    View Slide

20. View Slide

21. “Just finished, now what?”
    

    View Slide

22. Different people use
    different tools, have
    different backgrounds 

    and ways to work.
    

    View Slide

23. View Slide

24. Wiki
    Overall architecture of our system
    URLs to external services and 3rd-party libraries
    Development process and how to setup all the tools
    

    View Slide

25. Apr ‘18
    

    View Slide

26. Problem 2
    No process for 

    tech planning
    

    View Slide

27. Filipe, can you look at ticket X?
    

    View Slide

28. Sure!
    

    View Slide

29. I don’t like this approach..
    

    View Slide

30. There is an easier way to do that!
    

    View Slide

31. But I’ve just spent 2 days…
    

    View Slide

32. Request for Comments
    

    View Slide

33. View Slide

34. Code

    Review
    Start

    Feature
    Merge

    Feature
    Implementation phase
    

    View Slide

35. Create

    RFC
    RFC

    Approved
    Merge

    RFC
    Merge

    Feature
    Code

    Review
    Start

    Feature
    Implementation phase
    Design phase
    

    View Slide

36. View Slide

37. View Slide

38. View Slide

39. Request for Comments
    Fosters discussion within the team
    
    Serves as a historical report
    
    Newcomers can learn from previous colleagues
    

    View Slide

40. Jun ‘18
    

    View Slide

41. Jul ‘18
    

    View Slide

42. Problem 3
    Lack of information about
    past incidents
    

    View Slide

43. All of us had incidents in
    production or bugs 

    that lasted for a while
    

    View Slide

44. In teams that change
    frequently, information and
    learnt lessons get lost
    

    View Slide

45. The past years are a blackbox for me.
    

    View Slide

46. We will be destined to make
    the same mistakes if we
    don’t know what happened.
    

    View Slide

47. …even though the client
    expects that you know.
    

    View Slide

48. Postmortem
    

    View Slide

49. View Slide

50. Postmortem
    Clarifies and documents what happened
    
    Can potentially be shared with the management team or
    even the client
    
    Your future colleagues can learn from past mistakes
    

    View Slide

51. Dec ‘18
    

    View Slide

52. Problem 4
    Pull Requests with 

    no description
    

    View Slide

53. In a mobile application, a
    simple change can have a
    big UI impact
    

    View Slide

54. Descriptive Pull Requests
    

    View Slide

55. View Slide

56. Mar ‘19
    

    View Slide

57. New team means new
    dynamics
    

    View Slide

58. I prefer to discuss face to face
    

    View Slide

59. Results
    Saved my future self countless times
    Wrote reports of problems we had in production
    Documented processes, architectures, integrations etc.
    

    View Slide

60. My first month
    Need to mental-map the interactions..
    

    View Slide

61. Colleague’s first Month
    Yes, it was easy to pick-up!
    

    View Slide

62. Colleague’s first Month
    YAY, first time in 3 years that it was easy!
    

    View Slide

63. Former colleague’s 

    last week
    Wish we had RFCs when I started
    

    View Slide

64. Former colleague’s 

    last week
    It would’ve prevent a few discussions
    

    View Slide

65. We do a great job if our
    team is not dependent on us
    

    View Slide

66. Documentation is for the
    team/project, not the
    individuals
    

    View Slide

67. Slowly introduce
    documentation in your team
    

    View Slide

68. I have an RFC for you to review
    

    View Slide

69. Im writing a Doc for the Redesign
    

    View Slide

70. Thank him, it’s been very useful!
    ?
    

    View Slide

71. View Slide

72. Thank you
    Filipe Mendes
    @fmendes6

    medium.com/@fmendes6
    

    View Slide

73. References
    https://buriti.ca/6-lessons-i-learned-while-implementing- technical-rfcs-as-a-management-
    tool-34687dbf46cb, Juan Buriticá (2017)
    https://github.com/rust-lang/rfcs, Rust Language
    https://csse.usc.edu/events/2002/arr/letters.pdf, Manifesto Elicits Cynicism, Steven Rakitin (2002)
    https://ieeexplore.ieee.org/document/914732, J.D. Herbsleb, D. Moitra (2001)
    https://zeldauniverse.net/media/fonts, Zelda Universe
    https://proandroiddev.com/perfecting-process-for-presenting-prs-7b3c63cd2848, Perfecting
    process for Presenting PRs, Ataul Munim (2019)
    https://www.youtube.com/watch?v=xSlqpsdBQx4, Game Over - Zelda, PenguinIceNinja (2007)
    https://www.candyspace.com/team/, Candyspace (2019)
    https://github.com/novoda/novoda/blob/master/.github/PULL_REQUEST_TEMPLATE.md, Novoda
    (2017)
    

    View Slide