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


Ecdea9b9714877b86cee08458f085481?s=47 Tania Allard
November 13, 2019


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

More Decks by Tania Allard

Other Decks in Programming


  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. 2 bit.ly/ato-docs-culture Get the slides @ixek bit.ly/ato-docs-culture

  3. 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
  4. 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
  5. who likes writing documentation? 5 @ixek bit.ly/ato-docs-culture

  6. who actually writes documentation as a regular practice? 6 @ixek

  7. 7 What if you could change your work culture… writing

    documentation? @ixek bit.ly/ato-docs-culture
  8. 8 and pay some technical debt? @ixek bit.ly/ato-docs-culture

  9. What is technical debt?

  10. It’s like the monster under your bed 10 @ixek bit.ly/ato-docs-culture

  11. Technical debt A series of bad decisions 11 WHAT I

    DO Leading to error prone code & architecture @ixek bit.ly/ato-docs-culture
  12. 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
  13. What decisions were made in the past? That prevent me

    from getting stuff done today @ixek
  14. What causes technical debt? 14 @ixek bit.ly/ato-docs-culture

  15. 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
  16. Unnecessary complexity 16 @ixek bit.ly/ato-docs-culture

  17. 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
  18. 18 Identifying technical debt @ixek bit.ly/ato-docs-culture

  19. 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
  20. 20 https://xkcd.com/2054/ House of cards effect - Infra smells @ixek

  21. 21 https://xkcd.com/1794/ Everything is on FIRE - all the time

    @ixek bit.ly/ato-docs-culture
  22. 22 Courtesy of Ashley Mcnamara Everything is on FIRE -

    all the time @ixek bit.ly/ato-docs-culture
  23. 23 Unstable or underutilized data dependencies @ixek bit.ly/ato-docs-culture

  24. 24 Pipeline jungles @ixek bit.ly/ato-docs-culture

  25. 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
  26. 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
  27. 27 Story time @ixek bit.ly/ato-docs-culture

  28. 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
  29. 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
  30. 30 You are given a present • You will be

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

    Ashley Mcnamara @ixek bit.ly/ato-docs-culture
  32. 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
  33. 33 http://docs.astropy.org/en/stable/index.html#developer-documentation Write as if your best friend is reading

    @ixek bit.ly/ato-docs-culture
  34. 34 http://docs.astropy.org/en/stable/development/docguide.html Confusing - get newcomers to contribute Critical fixes

    have been found this way! @ixek bit.ly/ato-docs-culture
  35. 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
  36. 36 https://alexjs.com/ VIsual Studio Code Extension https://cda.ms/146 @ixek bit.ly/ato-docs-culture

  37. “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
  38. 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
  39. If you cannot use the mindful structure You might need

    to refactor 39 @ixek bit.ly/ato-docs-culture
  40. 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
  41. 41 https://azure.microsoft.com/en-us/resources/samples/?sort=0 Give them useful starting points @ixek bit.ly/ato-docs-culture

  42. 42 Make the abstract tangible @ixek bit.ly/ato-docs-culture

  43. 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
  44. 44 https://speakerdeck.com/inesmontani/let-them-write-code-keynote-pycon-india-2019 Design patterns @ixek bit.ly/ato-docs-culture

  45. 45 https://speakerdeck.com/inesmontani/let-them-write-code-keynote-pycon-india-2019 Design patterns and users @ixek bit.ly/ato-docs-culture

  46. 46 Bye bye manual docs @ixek bit.ly/ato-docs-culture

  47. 47 https://github.com/pycco-docs/pycco Bye bye manual docs @ixek bit.ly/ato-docs-culture

  48. 48 https://www.sphinx-doc.org/en/master/usage/quickstart.html Bye bye manual docs Because they are part

    of your pipelines @ixek bit.ly/auto-docs-culture
  49. • 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
  50. 50 Make it a joy writing the docs @ixek bit.ly/ato-docs-culture

  51. 51 Recognise docs writers @ixek bit.ly/ato-docs-culture

  52. 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
  53. Expose code smells 53 Why docs? Keeps institutional knowledge Protects

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

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

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