Posted on Friday, Apr 2, 2021
In this episode we discuss several aspects of 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.
  • 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: 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
  • Gitlab’s handbook has a lot of good ideas
  • The more experienced you are, the more should you document
  • Tools for generating documentation web sites
  • Example of collecting documentation from multiple projects and creating a documentation site using Zola:
  • The TMPDIR handbook:
  • Jupyter Notebook
  • Treat documents as code, and code as documents!

Available on your favorite podcast platform.

Discuss this episode at our community site.


Cliff Brake

Cliff Brake

Cliff has been developing products for a long time. See BEC and Github for more information.

Khem Raj

Khem Raj

Khem is an OpenEmbedded maintainer.