Re: PATCH: improve git switch documentation
- From
- Martin <git@mfriebe.de>
- Date
- Jul 17, 2021, 10:07 UTC
- Message-ID
- <e57f1d19-d574-5ba5-efc1-abb8ab2a8c01@mfriebe.de>
- In-Reply-To
- <60f22aaa6a4f1_1f602081b@natae.notmuch>
On 17/07/2021 02:56, Felipe Contreras wrote:
Show 10 quoted lines
> Martin wrote: > It is the Socratic method. If I tell you "the user will think X" you are > not going to believe me. Therefore I'm asking you what the user will > think. > >> But no one is taking them by the hand. No one is asking all those >> questions to them. >> So they (new users) will not always make that conclusion. > > What conclusion would they reach?
You realize that your question makes no sense?
If the user does not enter the state of concluding, then they will not reach a conclusion at all.
If you want to challenge my statement, that the user does not start concluding, then you could ask me: Why? To which I have to admit, I do not know, I did not ask those who didn't. And frankly it does not matter. Lets assume we knew "why". Then to remedy that cause, some change would be needed. So most likely the doc would need to be changed to have some trigger added, to overcome that reason. In the end, that means more info in the doc. Same as what is already proposed.
Show 5 quoted lines
>>> What do they think it will happen? >> >> They do not think about it at all. > > This doesn't make any sense. They used -C instead of -c for a reason.
For the 4th or 5th time (not going to count the exact number of times I have answered the exact same question)
The reason is the branchname was used, and the wanted to use it again. The doc says they can use it again. So that is all they want at that moment.
Why is there an extra option for doing this, good question but to them at that point in time: not relevant. The doc of the option does not say, that there may be any consequences, so that is good enough at that moment.
If you want, you can call them ignorant. But in their defence they may not even know that. They have whatever other issues to solve at that time. They are happy to have found that option, and they really need to return to whatever other stuff they were doing. So they trust the docs, and the docs have no explicit warning.
Frankly all the above, is a very common pattern that lots of people show at some time or another. Whatever the problem, people go for whatever *appears* to be the easy fix. No thought on what will happen after that. In German their is a saying "Nach mir die Sinnflut".
Show 7 quoted lines
>> >> Because they did not correctly understand what the net protected the from. > > Users should not be executing commands they don't understand. If a user > doesn't understand what `git delete-this-branch` does, then he shouldn't > run it. >
How can they check they understand it?
See also the example of the person that makes *two* the conclusions. How can they tell there is nothing further that they need to conclude?
> If the documentation says a command overwrites a branch, and the user > runs the command anyway,
So is that an admission that people may not always come to the conclusion? I.e., what I said: They do not think about that part at all.
> and the branch is overwritten, git did what the
> user told it to do, and what happened is the responsibility of the user.
Well, that is a matter of philosophical debate.
It does not say "commits may be affected". I think or hope, that we can agree the effect on commits is something, that is to be concluded. The discrepancy we have is, whether it will be concluded by all users ("all" is to mean a high percentage leaving no significant rest).
If we agree on that "conclusion" statement, then the discrepancy we have can be further deducted on whether there is such an "significant rest" amount of users.
I believe there is. You do afaik not believe this.
But if there is (or "if there were") such an significant amount of users, then it would be a valuable addition to add text, that add the result of that conclusion.
So then all the "what would they think..." question do not really matter. It does not matter what they think, if it is not what they are expected to think. If there is a significant amount of people who for any reason whatsoever do not think this, then I believe the documentation should respect the fact, that those people exist (and more than just as an exception).
Show 9 quoted lines
>>> Let me try yet another analogy. >>> >>> If an alarm clock has two buttons "snooze" and "off". >> How exactly is that connected? >> This is a random story. Not an analogy. > > The fact that you don't see the analogy doesn't mean it isn't one. > > Did the user click "off" for a reason?
"Off" is not called "force snooze". Off does not require to conclude info, as "-C" does.
Lets say, there is a "change timezone" and a "force change timezone" button, and the first one would reject to work, if an alarm is active, the 2nd would work even if an alarm exists. Then that would be an analogy. Because then the user has to figure out, that changing the timezone would change the displayed hour, and as a consequence clear the alarm.
In your example, where is the conclusion the user has to make?
Show 5 quoted lines
>>> Mistook it for what? What did they expect it was going to happen? >> I have answered that in great detail, at least 3 times in this mail thread. > > I'm sorry, but no, "they'll think nothing and they'll do it for no > reason" is not an answer.
Well, that is not what I wrote.