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

                  285 Listeners

                  LINUX Unplugged by Jupiter Broadcasting

                  LINUX Unplugged

                  263 Listeners

                  This Week in Linux by TuxDigital Network

                  This Week in Linux

                  36 Listeners

                  Self-Hosted by Jupiter Broadcasting

                  Self-Hosted

                  135 Listeners

                  The Agile Embedded Podcast by Luca Ingianni, Jeff Gable

                  The Agile Embedded Podcast

                  11 Listeners