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

2y ago 36:27

https://brainsandbeards.com, Wojciech Ogrodowczyk, and Patryk Peszko에서 제공하는 콘텐츠입니다. 에피소드, 그래픽, 팟캐스트 설명을 포함한 모든 팟캐스트 콘텐츠는 https://brainsandbeards.com, Wojciech Ogrodowczyk, and Patryk Peszko 또는 해당 팟캐스트 플랫폼 파트너가 직접 업로드하고 제공합니다. 누군가가 귀하의 허락 없이 귀하의 저작물을 사용하고 있다고 생각되는 경우 여기에 설명된 절차를 따르실 수 있습니다 https://ko.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 에피소드

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.

들어볼 가치가 있는 팟캐스트