BBS 19: Documentation In Software Projects Brains & Beards Show podcast

5M ago 36:27

Content provided by https://brainsandbeards.com, Wojciech Ogrodowczyk, and Patryk Peszko. All podcast content including episodes, graphics, and podcast descriptions are uploaded and provided directly by https://brainsandbeards.com, Wojciech Ogrodowczyk, and Patryk Peszko or their podcast platform partner. If you believe someone is using your copyrighted work without your permission, you can follow the process outlined here https://player.fm/legal.

Key Moments:

Documentation comes in different forms like code comments, README files, external documentation in Confluence, and architectural decision records (ADRs).
Code comments can become outdated over time as the code changes, so it's better to rely on clear naming, TypeScript types, and unit tests to document code.
README files should focus on project-specific setup instructions rather than general language/framework documentation, and link to external docs when possible.
External documentation is better suited for business context, team decisions, and diagrams that involve multiple teams. It's easier for others to contribute to compared to code docs.
Using a shared terminology ("domain language") is important for communication between teams working on the same codebase or product. This vocabulary should be documented.
ADRs are useful for documenting past architecture and design decisions in case they need to be revisited. They improve decision making and prevent rehashing the same discussions.
Writing documentation forces one to better understand a topic. Developers should practice writing to improve their communication and learning.
Tests can double as a form of documentation, like regular expressions explained through example test cases.
Commit messages should be concise and avoid too many changes in one commit to allow for informative messages.
TypeScript's "expect error" is better than "ignore" for documenting expected errors in code.

20 episodes

Key Moments:

Documentation comes in different forms like code comments, README files, external documentation in Confluence, and architectural decision records (ADRs).
Code comments can become outdated over time as the code changes, so it's better to rely on clear naming, TypeScript types, and unit tests to document code.
README files should focus on project-specific setup instructions rather than general language/framework documentation, and link to external docs when possible.
External documentation is better suited for business context, team decisions, and diagrams that involve multiple teams. It's easier for others to contribute to compared to code docs.
Using a shared terminology ("domain language") is important for communication between teams working on the same codebase or product. This vocabulary should be documented.
ADRs are useful for documenting past architecture and design decisions in case they need to be revisited. They improve decision making and prevent rehashing the same discussions.
Writing documentation forces one to better understand a topic. Developers should practice writing to improve their communication and learning.
Tests can double as a form of documentation, like regular expressions explained through example test cases.
Commit messages should be concise and avoid too many changes in one commit to allow for informative messages.
TypeScript's "expect error" is better than "ignore" for documenting expected errors in code.

Podcasts Worth a Listen