BBS 19: Documentation in Software Projects

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/ 

There are no comments yet.

Please log in to write the first comment.