BBS 19: Documentation in Software Projects

Brains & Beards Show

https://brainsandbeards.com/

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.

👋 Visit us on https://brainsandbeards.com/