Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

More Decks by Filipe Mendes

Other Decks in Programming


  1. @fmendes6

  2. “The resistance to documentation among developers is well known and

    needs no emphasis.” - D.Herbsleb & D. Moitra, 
 Global Software Development, IEEE, 2001
  3. Have you ever needed some form of information from someone

    that was unavailable?
  4. What is this system? How does it work? Why was

    it created this way?
  5. 2017

  6. Mar ‘18

  7. A vailable

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

  9. Documentation
 Android team

  10. None
  11. Problem 1 Lack of knowledge 
 about the app

  12. Filipe, can you look at ticket X?

  13. Hum…suuuure!

  14. Ask And Continue Do not Ask and Continue Quit

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

  16. What if your colleagues 
 are unavailable?

  17. A dependency is a 
 problem if it blocks you

 from progressing
  18. Wiki

  19. None
  20. “Just finished, now what?”

  21. Different people use different tools, have different backgrounds 

    ways to work.
  22. None
  23. Wiki Overall architecture of our system URLs to external services

    and 3rd-party libraries Development process and how to setup all the tools
  24. Apr ‘18

  25. Problem 2 No process for 
 tech planning

  26. Filipe, can you look at ticket X?

  27. Sure!

  28. I don’t like this approach..

  29. There is an easier way to do that!

  30. But I’ve just spent 2 days…

  31. Request for Comments

  32. None
  33. Code
 Review Start
 Feature Merge
 Feature Implementation phase

  34. Create
 Approved Merge
 RFC Merge
 Feature Code

 Feature Implementation phase Design phase
  35. None
  36. None
  37. None
  38. Request for Comments Fosters discussion within the team Serves as

    a historical report Newcomers can learn from previous colleagues
  39. Jun ‘18

  40. Jul ‘18

  41. Problem 3 Lack of information about past incidents

  42. All of us had incidents in production or bugs 

    that lasted for a while
  43. In teams that change frequently, information and learnt lessons get

  44. The past years are a blackbox for me.

  45. We will be destined to make the same mistakes if

    we don’t know what happened.
  46. …even though the client expects that you know.

  47. Postmortem

  48. None
  49. 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
  50. Dec ‘18

  51. Problem 4 Pull Requests with 
 no description

  52. In a mobile application, a simple change can have a

    big UI impact
  53. Descriptive Pull Requests

  54. None
  55. Mar ‘19

  56. New team means new dynamics

  57. I prefer to discuss face to face

  58. Results Saved my future self countless times Wrote reports of

    problems we had in production Documented processes, architectures, integrations etc.
  59. My first month Need to mental-map the interactions..

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

  61. Colleague’s first Month YAY, first time in 3 years that

    it was easy!
  62. Former colleague’s 
 last week Wish we had RFCs when

    I started
  63. Former colleague’s 
 last week It would’ve prevent a few

  64. We do a great job if our team is not

    dependent on us
  65. Documentation is for the team/project, not the individuals

  66. Slowly introduce documentation in your team

  67. I have an RFC for you to review

  68. Im writing a Doc for the Redesign

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

  70. None
  71. Thank you Filipe Mendes @fmendes6

  72. 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)