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