Talk: Mason Egger - Building Docs like Code: Continuous Integration for Documentation

Presented by:
Mason Egger

It is common for developers to overlook the documentation of their works. They are either on a time crunch, lack the proper tooling, or simply just forget to create and update the documentation. Whatever the cause behind this, it is not a proper excuse for not keeping the documentation up to date. However, for all our development processes there are few as neglected as the documentation process. Documentation should be treated as important as the code that makes up the project. So, let’s move the documentation into the code. With modern documentation tools such as MkDocs and Sphinx, both of which are Python powered tools, and Continuous Integration tools we can now include docs in the commit. They can be reviewed in code reviews, built and versioned in a CI tool, and even tested for things such as correct code examples and broken links. This is the process that the developer knows, understands, and enjoys. I introduced a team to this exact workflow and a working pipeline; all they had to do was keep the documentation up to date. This team currently has some of the most up to date documentation in a company of near two thousand engineers, and they never complain about writing/updating documentation. It’s just part of the workflow.

Attendees will walk away with a new mindset on how to handle documentation, a list of tools that can aid in this process, and a proven, easy-to-implement method that works well for real engineers in a production setting.

[marzak]

Great talk! I feel that I am not alone in forcing everyone to doc everything) And now I know the workflow that can be implemented more smoothly! Thanks!

[michaskowron]

I really enjoyed your talk. I'm a Tech Writer (now mostly a coding Tech Writer) and I'm more than happy to see that an engineer talks about docs with such enthusiasm. Great job!

[bandaangosta]

Totally recommended talk. Mason gives a very complete and entertaining presentation. Perfect timing as I was just given the task to propose a way to improve our very defficient code documentation. I only wish you had gone a little deeper on the pydoc path, which I am (was?) planning to use. Thanks!

[nilsmuller]

Such a great talk, thank you Mason! It's the first PyCon 2020 talk that really wants me to change my workflow. :)

[RedspartHD]

Fantastic talk! Going to look into incorporating mkdocs into my project.

[Erotemic]

I agree, doctests are criminally underused.

[mc_bobs]

We use mkdocs extensively in my organisation for documentation and some of our pages are huge - around ~10000 lines of markdown over a period of time. The gh-deploy command sometimes doesn't update the github pages correctly until I do a git pull which has a forced update and then do a mkdocs gh-deploy manually. This occur on pages which has child elements and is denoted by and collapse/expand [+] button by mkdocs. @Mason - Have you faced this issue?