Hacker News new | ask | show | jobs
by swat535 14 days ago
If your system's public API requires me to understand all the internals to use it, then it's indeed confusing.
1 comments

The common stance is that people try to use said API without reading the docs. Like the first paragraphs of the git-rebase description

  Transplant a series of commits onto a different starting point. You can also use git rebase to reorder or combine commits: see INTERACTIVE MODE below for how to do that.
And then later

  Rebasing interactively means that you have a chance to edit the commits which are rebased. You can reorder the commits, and you can remove them (weeding out bad or otherwise unwanted patches).
Those are obvious IF you know what a commit is and how they relate to each other (a DAG). But most people don’t. Instead, their only knowledge is what they’ve seen the operation do (tutorial or youtube video).

Git itself has a glossary[0] of the terms used in the docs.

[0] https://git-scm.com/docs/gitglossary/2.54.0