Episode 10
Documentation
In this episode we discuss several aspects of documentation.
The TMPDIR podcast · Cliff Brake and Khem Raj
April 2, 202140m 15s
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: 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
- 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: https://github.com/simpleiot/docs.simpleiot.org
- 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.