3 ms·
The analogy makes no sense. Small docs aren't like small code commits. Small doc commits are like small code commits, and I agree you don't want to commit walls
by TeMPOraL 2y ago
The analogy makes no sense. Small docs aren't like small code commits. Small doc commits are like small code commits, and I agree you don't want to commit walls of text. But that's because commits are deltas - they can be small, because they're not standalone - they make no sense without the underlying (large) codebase being available to the reader.
So where the article proposes:
> Self-contained context
> Include all the necessary background so the reviewer doesn’t need to dig into other docs for clarity
That means, by necessity, that your "small docs" will either be so shallow and context-free that they're not worth writing down in the first place, or will be 90%+ context copy-pasted from one "small doc" to another, at which point you might want to just merge them into one bigger doc and introduce a hierarchy. So, just like code.
(And reviews are always the bottleneck for code, too. Similarities abound.)
- deleted 2y ago[deleted]
- ricardobeat 2y agoLooks like you got stuck on that first paragraph. The author doesn’t even make an analogy between small commits and small docs, it’s just used as a hook for the intro.
- TeMPOraL 2y agoI disagree. I believe it's the load-bearing analogy that's carrying all the ideas in the article. Consider e.g. the sections "The benefits of small docs" and "Avoid blocking yourself during reviews" - they're mostly about workflow. They apply to changesets, not the artifact itself. I feel like there's an implied assumption in the article, that documents are always submitted and reviewed wholesale, so to get the benefits of small commits, you need to make the document small enough to qualify as a small commit. If that's the idea, then I disagree with it.