Artwork

תוכן מסופק על ידי https://brainsandbeards.com, Wojciech Ogrodowczyk, and Patryk Peszko. כל תוכן הפודקאסטים כולל פרקים, גרפיקה ותיאורי פודקאסטים מועלים ומסופקים ישירות על ידי https://brainsandbeards.com, Wojciech Ogrodowczyk, and Patryk Peszko או שותף פלטפורמת הפודקאסט שלהם. אם אתה מאמין שמישהו משתמש ביצירה שלך המוגנת בזכויות יוצרים ללא רשותך, אתה יכול לעקוב אחר התהליך המתואר כאן https://he.player.fm/legal.
Player FM - אפליקציית פודקאסט
התחל במצב לא מקוון עם האפליקציה Player FM !

BBS 19: Documentation in Software Projects

36:27
 
שתפו
 

Manage episode 389671722 series 3271778
תוכן מסופק על ידי https://brainsandbeards.com, Wojciech Ogrodowczyk, and Patryk Peszko. כל תוכן הפודקאסטים כולל פרקים, גרפיקה ותיאורי פודקאסטים מועלים ומסופקים ישירות על ידי https://brainsandbeards.com, Wojciech Ogrodowczyk, and Patryk Peszko או שותף פלטפורמת הפודקאסט שלהם. אם אתה מאמין שמישהו משתמש ביצירה שלך המוגנת בזכויות יוצרים ללא רשותך, אתה יכול לעקוב אחר התהליך המתואר כאן https://he.player.fm/legal.

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/

  continue reading

20 פרקים

Artwork
iconשתפו
 
Manage episode 389671722 series 3271778
תוכן מסופק על ידי https://brainsandbeards.com, Wojciech Ogrodowczyk, and Patryk Peszko. כל תוכן הפודקאסטים כולל פרקים, גרפיקה ותיאורי פודקאסטים מועלים ומסופקים ישירות על ידי https://brainsandbeards.com, Wojciech Ogrodowczyk, and Patryk Peszko או שותף פלטפורמת הפודקאסט שלהם. אם אתה מאמין שמישהו משתמש ביצירה שלך המוגנת בזכויות יוצרים ללא רשותך, אתה יכול לעקוב אחר התהליך המתואר כאן https://he.player.fm/legal.

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/

  continue reading

20 פרקים

כל הפרקים

×
 
Loading …

ברוכים הבאים אל Player FM!

Player FM סורק את האינטרנט עבור פודקאסטים באיכות גבוהה בשבילכם כדי שתהנו מהם כרגע. זה יישום הפודקאסט הטוב ביותר והוא עובד על אנדרואיד, iPhone ואינטרנט. הירשמו לסנכרון מנויים במכשירים שונים.

 

מדריך עזר מהיר