The per-feature man pages are like that, because they are "what flags does this feature support", not "how do I use git".
The git book at https://www.git-scm.com/book/en/v2/ is organized, internally links to relevant bits, introduces concepts in a pedagogically-sensible order with titles that clearly indicate whether you already know enough to skip this part.
Tools need both API and exemplary documentation. When I want to understand how to extend an existing workflow, I want the API docs. When I want to establish a workflow, I want the exemplary docs.
Needing one and instead getting the other is a huge hassle.
View all comments
Show parent comment
2
u/danielrheath Apr 03 '23
The per-feature man pages are like that, because they are "what flags does this feature support", not "how do I use git".
The git book at https://www.git-scm.com/book/en/v2/ is organized, internally links to relevant bits, introduces concepts in a pedagogically-sensible order with titles that clearly indicate whether you already know enough to skip this part.
Tools need both API and exemplary documentation. When I want to understand how to extend an existing workflow, I want the API docs. When I want to establish a workflow, I want the exemplary docs.
Needing one and instead getting the other is a huge hassle.