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
Tweet

More Decks by Filipe Mendes

Other Decks in Programming

Transcript

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

    needs no emphasis.” - D.Herbsleb & D. Moitra, 
 Global Software Development, IEEE, 2001
  2. Wiki Overall architecture of our system URLs to external services

    and 3rd-party libraries Development process and how to setup all the tools
  3. Create
 RFC RFC
 Approved Merge
 RFC Merge
 Feature Code
 Review

    Start
 Feature Implementation phase Design phase
  4. Request for Comments Fosters discussion within the team Serves as

    a historical report Newcomers can learn from previous colleagues
  5. We will be destined to make the same mistakes if

    we don’t know what happened.
  6. 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
  7. Results Saved my future self countless times Wrote reports of

    problems we had in production Documented processes, architectures, integrations etc.
  8. 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)