Lab: document it well

Decide what to write where — READMEs, comments, commits, ADRs, changelogs.

Lab · optionalFundamentalsIntermediate9 min

Recommended first

By the end of this lesson you will be able to:

Optional scenario lab. Good documentation is mostly knowing what goes where. Practice those calls.

1.
Which is the best commit subject line?
fix stuffFix off-by-one in paginationchangesupdate code
2.
A good code comment most often explains:
What the code does, line by lineWhy it does it — the reason or trade-offNothing; comments are bannedThe author's mood
3.
You chose PostgreSQL over alternatives after weighing real trade-offs. Where should the reasoning live?
A throwaway code commentAn Architecture Decision RecordThe user-facing changelogNowhere; you'll remember
4.
A release renames a config option that users depend on. In the changelog this is:
Not worth mentioningA breaking change to flag prominentlyA minor internal noteOnly relevant to developers

The pattern: write for the person who arrives later with no context — usually you.

Finished reading? Mark it complete to track your progress.

Changelogs and release notes

Tell your users what changed, in language they care about.

Merge vs rebase

Two ways to combine branches, and how to choose between them.