Documentation
Episode Description
In this episode we discuss several aspects of documentation.
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
- 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.