3 ms·
> I think the disadvantage with this style of documentation is you can't really alter the commit message after it's written. That is not a disadvantage. The co
by masklinn 3y ago
> I think the disadvantage with this style of documentation is you can't really alter the commit message after it's written.
That is not a disadvantage. The commit is a historical record, if I come back to that commit 3 years later I want to know its purpose in the context it was in, I don’t want a whitewashed history.
> Compare that with documentation stored in a .md file, or even a Wiki or even Confluence. My colleague can write something and if I see a way to improve it I can go ahead and do that, and other colleagues can improve on what I've written.
That’s like comparing a bicycle and a goose.
> But I also myself find it tempting to describing the design of a particular component when I commit that component, and that's something I now avoid.
That’s a shame. Knowing the considerations (or lack thereof) and tradeoffs at time of creation are often useful to understand defects, either in the original, or in evolutions, or in changes of use case.
> Will the commit documentation just describe the differences?
Yeees?
> Then in order for a new team member to find out how the system works by reading the documentation they've got to read multiple commit messages and "merge" them in their head.
No, for that you maintain a separate “current” documentation, which does not need to cover implementation tradeoffs, or that the original was written under time crunch, or whatever.
- 20after4 3y agoI really love documentation that lives in the same repo with the code. My favorite is a .md file for every module, class or component. Some mixture of inline code docs and standalone docs is probably ideal. But docs as markdown that don't require some compile step to build the documentation, and doesn't require opening a browser to view them, is just so much better, IMO, compared to any sort of external docs like a wiki or html on a server somewhere that gets re-generated by a CI job.
- thrdbndndn 3y ago> That is not a disadvantage. The commit is a historical record OP's point is that, while commit message is indeed a historical record, documentation isn't (or shouldn't). If you double commit message as documentation, it would cause issues like wrong information confusing or misleading future readers because it's non-editable.
- Sprocklem 3y agoCrucially, however, the commit message is not documentation of the code, which would need to be changed and updated. Instead, it is documentation of the change, describing the reason for the change, what the code does to achieve that, and, if relevant, why you chose that solution. It provides necessary context to the already immutable diff and therefore need not be mutable itself.
- twosdai 3y agoSucks when you mess up in your commit message though and don't type the right thing.
- spencerchubb 3y agoIf you put docs in a markdown file, you will still be able to see what the markdown said at that time because it will also be in the commit history.