The TMPDIR podcast

Documentation

Listen Later

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.

                  ...more
                  View all episodesView all episodes
                  Download on the App Store
                  The TMPDIR podcastBy TMPDIR
                  • 5
                  • 5
                  • 5
                  • 5
                  • 5

                  5

                  3 ratings

                  More shows like The TMPDIR podcast

                  View all
                  The Changelog: Software Development, Open Source by Changelog Media

                  The Changelog: Software Development, Open Source

                  289 Listeners

                  LINUX Unplugged by Jupiter Broadcasting

                  LINUX Unplugged

                  268 Listeners

                  Embedded by Logical Elegance

                  Embedded

                  190 Listeners

                  Darknet Diaries by Jack Rhysider

                  Darknet Diaries

                  8,044 Listeners

                  The Agile Embedded Podcast by Luca Ingianni, Jeff Gable

                  The Agile Embedded Podcast

                  11 Listeners