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

GOOD CODE DOCUMENTS ITSELF AND OTHER LIES: CHANGING WORK CULTURE THROUGH DOCUMENTATION

Tania Allard
November 13, 2019

GOOD CODE DOCUMENTS ITSELF AND OTHER LIES: CHANGING WORK CULTURE THROUGH DOCUMENTATION

Most of us, developers, have heard at some point the phrase “good code documents itself” or any other of its variants such as “documentation outdates easily, the code does not”, “the code should walk you through how to do things”. Mainly as an excuse to not write documentation or to justify the lack thereof. I have worked with many teams and the lack of documentation is often one symptom of high technical debt.

But what if we could turn this around and use documentation like a driver for positive culture change and start paying the critical technical debt? Not only this approach helps the team to faster identify areas that need critical support but also brings in an important factor onto the table ‘empathy’.

In this talk, I will draw on my experiences using documentation as a weapon for positive culture and process change in machine learning and scientific computing environments. I will focus on the processes and approaches that enable the creation of documentation for data scientists, infrastructure and software engineering teams, and clients (without boring the teams to death or halting the technical development).

By the end of the talk team leaders, technical writers, documentation lovers, and software developers alike will have learned efficient techniques to make documentation a first-class citizen of the development cycles. They will also leave with one or two tricks on how to convince even the most reluctant dev to document the code.

Who and why?

This talk is suitable for anyone developing code at any level (or getting started) as well as for team leaders, open source maintainers, community leaders, documentation lovers, basically anyone. Basic understanding of what documentation and code are required.

What I really want people to take away is:

Change the perspective of what code means (it is not a boring piece of writing you need to write but much more)
How documentation can help small and big teams alike to pay technical debt
How you can use ‘documentation’ to change your work culture in a positive way

Tania Allard

November 13, 2019
Tweet

More Decks by Tania Allard

Other Decks in Programming

Transcript

  1. A ll T h i n g s o p

    e n Good Code Documents itself and other lies Changing Work culture through documentation Tania Allard, PhD Developer Advocate @Microsoft ixek / #AllThingsOpen DOI: 10.6084/m9.figshare.9989396
  2. ABOUT ME 3 ABOUT ME Open Source advocate I complex

    systems Machine learning / scientific computing I am also a mechanical keyboards lover @ixek bit.ly/ato-docs-culture
  3. 4 Takeaways Documentation as the entry point for paying technical

    debt Some useful tips to use docs to drive change What is technical debt? Your takeaways @ixek bit.ly/ato-docs-culture
  4. 7 What if you could change your work culture… writing

    documentation? @ixek bit.ly/ato-docs-culture
  5. Technical debt A series of bad decisions 11 WHAT I

    DO Leading to error prone code & architecture @ixek bit.ly/ato-docs-culture
  6. Technical debt A series of bad decisions 12 WHAT I

    DO Leading to using resources unnecessarily / with no clear objective @ixek bit.ly/ato-docs-culture
  7. What decisions were made in the past? That prevent me

    from getting stuff done today @ixek
  8. 15 That project was due yesterday! I’ll come back and

    clean tomorrow… or add the docs tomorrow Time crunch @ixek bit.ly/ato-docs-culture
  9. 17 All of our code is a pile of garbage…

    so nobody will notice if I add to the pile An already broken culture @ixek bit.ly/ato-docs-culture
  10. 19 Code Smells Indicators of a deeper problem (not bugs

    necessarily) Half-baked features Commented out pieces of code No test / broken tests Multiple versions of CI/CD but only one in use No documentation or poor documentation @ixek bit.ly/ato-docs-culture
  11. 22 Courtesy of Ashley Mcnamara Everything is on FIRE -

    all the time @ixek bit.ly/ato-docs-culture
  12. Burning everything to the ground 25 Refactor your code base

    Change your work culture -> make everyone accountable instead of pointing fingers Which is easier to do? @ixek bit.ly/ato-docs-culture
  13. Burning everything to the ground 26 Refactor your code base

    Change your work culture -> make everyone accountable instead of pointing fingers Which is More impactful to do? @ixek bit.ly/ato-docs-culture
  14. 28 You are given a present • But you have

    to figure out how to put it together • With no instructions @ixek bit.ly/ato-docs-culture
  15. 29 You are given a present • Some pieces might

    be missing so you will have to “build them as you go” • With minimal or no instructions • Some pieces will never fit • So you will need to build more pieces • Your present might never work - as you’d expect it @ixek bit.ly/ato-docs-culture
  16. 30 You are given a present • You will be

    miserable all the time @ixek bit.ly/ato-docs-culture
  17. Write the Docs!! Make the Docs valuable 31 Courtesy of

    Ashley Mcnamara @ixek bit.ly/ato-docs-culture
  18. Docs are part of the work - and the pipelines

    32 https://github.com/nteract/papermill No job is completed if there are no docs!! @ixek bit.ly/ato-docs-culture
  19. Master / Slave Blacklist / Whitelist 35 Problematic terms Inclusive

    culture not only in your docs Primary / Replica Denylist / Allowlist You’d be surprised on how a team can change @ixek bit.ly/ato-docs-culture
  20. “Code tells you how, comments tell you why” - Jeff

    Atwood Comments describe your code to developers 37 https://github.com/pandas-dev/pandas/blob/18a9e4c8ab253e83ba43767d890576186be13332/pandas/core/dtypes/concat.py#L72 Commenting vs documentation @ixek
  21. Docs describe its use and functionality to your users Mindful

    structure: - Explain the feature - Describe the use cases - Additional recommended tooling - Common errors / gotchas 38 https://github.com/pandas-dev/pandas/blob/18a9e4c8ab253e83ba43767d890576186be13332/pandas/core/dtypes/concat.py#L72 Commenting vs documentation @ixek
  22. If you cannot use the mindful structure You might need

    to refactor 39 @ixek bit.ly/ato-docs-culture
  23. The goal of the docs Help your users / developers

    to onboard and fast as possible Make the right choice Build trust 40 https://the-turing-way.netlify.com/introduction/introduction @ixek bit.ly/ato-docs-culture
  24. 43 Comic courtesy of Juliette Taka For the Open DreamKit

    project Who and why is using your tools? Abstractions, frameworks and use cases? - does it make sense @ixek bit.ly/ato-docs-culture
  25. • Schedule regular timings • Bring treats! • Let them

    choose • Review and merge - pair native and non native speakers Code sprints? Why not doc sprints? 49 @ixek bit.ly/ato-docs-culture
  26. They are the door to your code and your team

    culture 52 Why docs? Set the right mindset - for Pull Requests, code reviews, sprints planning Bring people back in the process So why docs? @ixek bit.ly/ato-docs-culture
  27. Expose code smells 53 Why docs? Keeps institutional knowledge Protects

    you against time churn So why docs? @ixek bit.ly/ato-docs-culture
  28. Are more likely to stay around 54 happy people (developers

    & users) @ixek bit.ly/ato-docs-culture
  29. Thank you & Get in touch 55 Come visit booth

    #20 tania.allard[at]microsoft.com ixek @ixek bit.ly/ato-docs-culture