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

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. 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 bit.ly/ato-docs-culture
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 bit.ly/ato-docs-culture
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