beginner friendliness

[tycobbb]

first off, cool piece of software, thanks for writing it. a piece of feedback about approachability, to do with what you will.

i found this tool while trying to figure out how to purge binary files from my git history so that i could manage them with git lfs instead. i'm not a novice programmer or git user, and it took me a long time to wade through the documentation to figure out how i should both install the tool and accomplish my task.

the readme, the redirections to the user manual, even the cli's basic help output are all extremely verbose (when --help overflows my terminal, i don't think it offers any extra utility over the manpage). after lots of digging, i found what i needed here. this feels like the sort of stuff that should be the first thing you see in the README (after an example install command).

i imagine many people are coming to this tool to do something they don't normally and perhaps shouldn't do generally (rewrite huge chunks of git history). it's an intimidating task. the documentation of this project tends towards a cold "authoritative description of capabilities" rather than a warm "here's how to get started". i understand that this could, in some sense, be by design, since these are operations that should not be taken lightly, but it's also a big drain on time and energy.

the tool is great, but it's for uncommon use cases. it might be nice to have (a version?) of the documentation organized in accordance with an understanding that most people are going to be approaching it for one-offs, that they're going to be performing emergency, just-in-time learning to accomplish a single task rather than trying to learn the tool's particularities front-to-back.

2¢, have a good one!

[newren]

Thanks for the feedback.

I might need a little more feedback about how to make such a change, though. In particular...

The "EXAMPLES" section of the manual has a bunch of very simple "problem description & one-liner command to do it" just like the page you linked to. It's true that this section is placed near the end of the manual (to be consistent with the style Git uses in its manuals), but I did make sure to mention the EXAMPLES section in the first section of the manual right after the overview of what kinds of things the tool could do. Is there something more that I could do here?

Also, in the README, right after the "How do I Install it?" section is the "How do I use it?" section (direct link: https://github.com/newren/git-filter-repo#how-do-i-use-it). The second sentence of that section is "If you prefer learning from examples...", after which it points to a bunch of simple "here's how to get started" examples, like the link you provided. In fact, that was one of the links. Is the problem that the first sentence mentions the manual with the examples starting from the second sentence, rather than mentioning the examples first?

Or am I missing the boat still?

[tycobbb]

i don't what the right solution is for this tool, and since i'm not going to be working on it i have no business saying so! but i do think that while striving for consistency with git's documentation might make this feel git-like, git is also not a tool known for its beginner-friendliness or ease-of-use. and its documentation-style certainly plays a part in that--it too tends towards the unix-y "authoritative description of capabilities".

looking for a few examples of tools that have what i think are user-friendly and example-forward documentation (it's actually pretty hard to find!)

https://github.com/sharkdp/fd https://github.com/httpie/httpie (ignoring the section asking for stars) https://github.com/git-duet/git-duet

the fd docs seem like they could be a really nice model for this!

[jenlampton]

Hello, also a new user here, but log-time git/GitHub user and open source contributor.

I'm also struggling with how to install this thing. I'm going to share my exact experience below, for some pity, and maybe also so that an experienced person might know what it's like to be new here :)

The "How to install" section talks about how "trivial" it is to install, but does not actually answer the question "How to install".

git-filter-repo is a single-file python script, which was done to make installation for basic use on many systems trivial: just place the script into your $PATH.

Okay, but -- which file do I need to download?

There are at least 15 listed in the github repository, and the one that looks the most like what I think "a single-file python script" might look like, git_filter_repo.py appears to be just an empty file :( It contains only a single line of text, which is the name of the project: git-filter-repo. So that can't be the file I need.

Since most projects I use are not "a single-file python script", they usually have releases with attached archives that I would download and extract. And from visiting the "Releases" page, it would appear the same thing is happening here. So, if I need to download and extract an archive, why even mention that this is "a single-file python script" in the installation instructions? Maybe move that to an about section or somewhere it won't confuse people into looking for a single file to install...

Okay, so I've now downloaded and extracted the latest release. I have a directory named git-filter-repo-2.x.x, am I supposed to move this whole thing into my $PATH? Or is there one file in there that I'm supposed to pull out and move? Instructions on what to do next would be helpful here

I don't know what to do with this, so I cd into the new directory of files to see if I recognize anything, and discover an INSTALL.md file. I open that up to see what to copy where, and I'm greeted with the information I really would have preferred to have 20 minutes ago :(

# Installation via Package Manager

Installation is as easy as
    $ PACKAGE_TOOL install git-filter-repo

Can we move that to the top of the "How to install" section of the README.md? Instead, I was immediately discouraged from reading the INSTALL.md file because the "How to install" section told me not to read it. :/

See INSTALL.md for things beyond basic usage or special cases.

[newren]

Instead, I was immediately discouraged from reading the INSTALL.md file because the "How to install" section told me not to read it. :/

Sorry about that. I've changed the relevant wording and inserted a new condition; it now reads as:

The more involved instructions are only needed if one of the following apply:

  * you do not find the above comment about trivial installation intuitively
    obvious

(followed, of course, by the previous list of reasons that were already there) I think that would have prevented all problems, as that page also explains which file is needed, i.e. git-filter-repo, and has the instructions on installing via package-manger for those who prefer it.

I once had the package manager section first, but that doesn't help if one of the package managers mis-packages the tool (something I have no control over), so I'll keep the "simple installation rules" primary on the INSTALL.md page.

[newren]

the readme, the redirections to the user manual, even the cli's basic help output are all extremely verbose (when --help overflows my terminal, i don't think it offers any extra utility over the manpage). after lots of digging, i found what i needed here. this feels like the sort of stuff that should be the first thing you see in the README (after an example install command).

I've reformatted the "How do I use it?" section of the README so that:

• It prefaces the link to the user guide with "For comprehensive documentation"
• It makes the guide you mentioned as helping you be the first link in the example section (previously it was the third) So, I think this should make it easier for folks like you to find this link you wanted.

Since we haven't come up with any concrete alternate ideas in the last year to improve this, I'll go ahead and close out, but hopefully these two changes help make things easier. Thanks both for your reports!

[tycobbb]

cheers =)