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

2y ago 36:27

Kongsi

Kandungan disediakan oleh https://brainsandbeards.com, Wojciech Ogrodowczyk, and Patryk Peszko. Semua kandungan podcast termasuk episod, grafik dan perihalan podcast dimuat naik dan disediakan terus oleh https://brainsandbeards.com, Wojciech Ogrodowczyk, and Patryk Peszko atau rakan kongsi platform podcast mereka. Jika anda percaya seseorang menggunakan karya berhak cipta anda tanpa kebenaran anda, anda boleh mengikuti proses yang digariskan di sini https://ms.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.

23 episod

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.

Podcast Berbaloi untuk Didengar