For most of Python's history, the predominant option for documentation has been Sphinx and reStructuredText. However, a majority of other ecosystems have adopted Markdown. There are historical reasons for reStructuredText being a better choice, however, Markdown is now up to the task.
In this talk, you'll learn why Markdown is a better option for your project's documentation. You'll be introduced to MkDocs, a static site generator built around Markdown content, and a series of associated plugins and extensions that you need to bring Sphinx-like capabilities to Markdown documentation. You'll also hear a case study of migrating multiple large, existing Sphinx-based documentation bases to Markdown, including the tools used for automating the process. You'll learn how you can engage the community to assist with the effort. Finally, you'll learn why it's worth the effort to make a change of this magnitude.
This talk is for anyone who is currently maintaining Sphinx documentation and is interested in migrating to a Markdown solution, or is interested in starting new documentation and wants to know what alternatives there are to Sphinx. I would consider this to be an intermediate level talk; folks who are brand new to open source contributing or programming will still get something out of it, but those who have some experience with documentation will benefit the most.
I am passionate about writing excellent, approachable documentation, and this talk is also about making your project’s documentation more approachable from a development perspective.
Kattni (she/her) is a creator, maker, photographer, programmer, classically trained vocalist, intermittent chef, air plant cultivator, casual knitter, and fledgling synth nerd. She is passionate about learning new things, and sharing her knowledge in an approachable way. She is tolerated by a cat and three kittens who continue to let her live with them.
She is a core development team member with the BeeWare project, where she focusses on improving the documentation and information architecture. She has orchestrated a complete shift of the documentation backend from Sphinx to MkDocs, as well as moving the website from Lektor to MkDocs. She is working on building a community around the project by, among other things, making contributing more approachable through various changes in their contribution process.
