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
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?
6. Mar ‘18
7. A vailable
 Documentation
8. Detailed Jira tickets, user stories, regression suites, glossaries, etc.
9. Documentation
 Android team
11. Problem 1 Lack of knowledge 
 about the app
12. Filipe, can you look at ticket X?
13. Hum…suuuure!
14. …
15. Ask And Continue Do not Ask and Continue Quit
16. I’m sorry, can you please help me?
17. What if your colleagues 
 are unavailable?
18. A dependency is a 
 problem if it blocks you 
 from progressing
19. Wiki
21. “Just finished, now what?”
22. Different people use different tools, have different backgrounds 
 and ways to work.
24. Wiki Overall architecture of our system URLs to external services and 3rd-party libraries Development process and how to setup all the tools
25. Apr ‘18
26. Problem 2 No process for 
 tech planning
27. Filipe, can you look at ticket X?
28. Sure!
29. I don’t like this approach..
30. There is an easier way to do that!
31. But I’ve just spent 2 days…
32. Request for Comments
34. Code
 Review Start
 Feature Merge
 Feature Implementation phase
35. Create
 RFC RFC
 Approved Merge
 RFC Merge
 Feature Code
 Review Start
 Feature Implementation phase Design phase
39. Request for Comments Fosters discussion within the team Serves as a historical report Newcomers can learn from previous colleagues
40. Jun ‘18
41. Jul ‘18
42. Problem 3 Lack of information about past incidents
43. All of us had incidents in production or bugs 
 that lasted for a while
44. In teams that change frequently, information and learnt lessons get lost
45. The past years are a blackbox for me.
46. We will be destined to make the same mistakes if we don’t know what happened.
47. …even though the client expects that you know.
48. Postmortem
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
51. Dec ‘18
52. Problem 4 Pull Requests with 
 no description
53. In a mobile application, a simple change can have a big UI impact
54. Descriptive Pull Requests
56. Mar ‘19
57. New team means new dynamics
58. I prefer to discuss face to face
59. Results Saved my future self countless times Wrote reports of problems we had in production Documented processes, architectures, integrations etc.
60. My first month Need to mental-map the interactions..
61. Colleague’s first Month Yes, it was easy to pick-up!
62. Colleague’s first Month YAY, first time in 3 years that it was easy!
63. Former colleague’s 
 last week Wish we had RFCs when I started
64. Former colleague’s 
 last week It would’ve prevent a few discussions
65. We do a great job if our team is not dependent on us
66. Documentation is for the team/project, not the individuals
67. Slowly introduce documentation in your team
68. I have an RFC for you to review
69. Im writing a Doc for the Redesign
70. Thank him, it’s been very useful! ?
72. Thank you Filipe Mendes @fmendes6
 medium.com/@fmendes6
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)