$30 off During Our Annual Pro Sale. View Details »

The legend of documentation

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.

Filipe Mendes

June 03, 2019
Tweet

More Decks by Filipe Mendes

Other Decks in Programming

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. 2017

    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