Re: Re: Unify annotated and non-annotated tags

From: Philip Oakley <philipoakley@iee.org>
Date: Dec 24, 2017, 12:33 UTC
Message-ID: <99FE6DCAB81A4510ACF961290988C094@PhilipOakley>
In-Reply-To: <CAPkN8xL1tUszvMuwwrc1ym6B6R5TzE4G9jKQ08oY2O_VPc8K_w@mail.gmail.com>

From: "anatoly techtonik" <techtonik@gmail.com>

Show 9 quoted lines

> From: Philip Oakley
> > So if I understand correctly, the hope is that `git show-ref --tags` 
> > could
> > get an alternate option `--all-tags` [proper option name required...] 
> > such
> > that the user would not have to develop the rather over the complicated
> > expression that used a newish capability of a different command.
>
> > Would that be right?

> That's correct.

> > Or at least update the man page docs to clarify the annotated vs
> > non-annotated tags issue (many SO questions!).

> Are there stats how many users read man pages and what is their
> reading session length? I mean docs may not help much,

The "reading the manual" question is fairly well answered in the Human Error literature in terms of clarity and effectiveness, and the normal human error rates (for interest search for "Panko" "Spreadsheet errors" [1]). Typical human error rate is 1%. Most pilot error ends up being, in part, caused by confusing / incomplete manuals (i.e. we fail to support them).

If the manuals are the peak of perfection then they are well visited and the supporting material is usually good. If manuals are a sprawling upland with bogs, fissure, islands of inaccessability, then they are rarely used.

Git does suffer from having a lot of separate commands, which makes seeing the woods for the trees difficult sometimes, especially as its core concepts are not always well understood.

Improving the manuals (as reference material) will always help, even if the trickle down effect is slow (made worse by alternate sources of error - Stackoverflow and blogs... ;-)

Show 5 quoted lines

> > And indicate if the --dereference and/or --hash options would do the 
> > trick!
> > - maybe the "^{}" appended would be part of the problem (and need that 
> > new
> > option "--objectreference" ).

Show 5 quoted lines

> --dereference would work if it didn't require extra processing.
> It is hard to think about other option name that would give
> desired result.
> ---
> anatoly t.

-- Philip

[1] https://arxiv.org/abs/1602.02601 https://arxiv.org/pdf/1602.02601 "This paper reviews human cognition processes and shows first that humans cannot be error free no matter how hard they try, and second that our intuition about errors and how we can reduce them is based on appallingly bad knowledge."