Documentation

Show Notes

In this episode we discus:

• What is documentation
• Benefits of documentation
• Documentation is critical for scaling, collaboration, and distributed teams
• How documentation benefits ourselves
• Lesli Lamport’s thoughts: To think, you have to write. If you’re thinking without writing, you only think you’re thinking.
  • https://www.microsoft.com/en-us/research/wp-content/uploads/2016/07/leslie_lamport.pdf
• Code should not only be created for the compiler, but more importantly for other people
• Importance of idioms, automatic code formatting, and code linters
• Documentation should live close to the code (embedded in the code, or Markdown in the same repository)
• Benefits of Markdown
• Trade-offs between Markdown and other formats like Word
• How to optimize documentation for collaboration
• Biggest problem with documentation is that most of it gets stale and how to prevent this
• Documentation can be a platform for thinking about a design
• Discussion should happen around documentation, not the other way around
• Use CI tools to publish your documentation
• Useful tools: draw.io and Typora
• The futility of emailing documents
• Storing documents in Git and using pull requests (PRs) is a hugely beneficial for collaboration
• Cal Newport’s new book: A world without email
  • https://www.calnewport.com/books/a-world-without-email/
• Gitlab’s handbook has a lot of good ideas
  • https://about.gitlab.com/handbook/
• The more experienced you are, the more should you document
• Tools for generating documentation web sites
  • Docusaurus
  • Docsy (Hugo)
  • Pandoc
  • mdBook
  • mkdocs
  • Zola
    • book theme
  • GitBook
• Example of collecting documentation from multiple projects and creating a documentation site using Zola: https://github.com/simpleiot/docs.simpleiot.org
• The TMPDIR handbook:
  • https://gitlab.com/tmpdir/handbook
• Jupyter Notebook
  • https://jupyter.org/
• Treat documents as code, and code as documents!

Available on your favorite podcast platform.

Discuss this episode at our community site.

Hosts