Documentation with mkdocs

simple and effective tool for creating beautiful docs

Ivan (@vanzaj)

force feeding
code quality measure

Documentation Driven Development

Documentation Driven Development

Readme Driven Development

Readme Driven Development

Write Greate Documentation

Jacob talking about docs writing

"... great documentation is what drives developer adoption."

— Jacob Kaplan-Moss

Django...

 
  • ~80,000 lines of Python
  • ~120,000 lines of English
  • 4x the length of the New Testament
  • 2x the length of Infinite Jest

What to write

 
  • step-by-step tutorials
  • overviews and topical guides
  • low-level reference material
 
Auto-generated documentation is almost worthless... most of the time it’s easier just to read the source than to navigate the bullshit that these autodoc tools produce.
Write the docs home page
Python docs with Sphinx
Sphinx project home page
ReStructuredText home page
Read The Docs theme
MkDocs project home page

Documentation as code

  • treat it as a separate project
  • separate content from presentation
  • must be under version control
  • automate processing & publishing steps
PUGS home page

Things to try

  • files organization in subsections
  • links to internal pages
  • links to internal images
GIT all the things
try git