SoylentNews
SoylentNews is people
https://soylentnews.org/

Common Joe writes:

I'd like some feedback from those on Soylent News about a personal project of mine -- a "unique" Git glossary. (After looking at a few terms, it should be clear what makes it unique from other Git glossaries.)

For those who use Git, it's pretty well known that Git documentation is... how shall I put this nicely? Git documentation is "difficult to understand" at times.

I never learned Git from more experienced people at the places I worked, because the groups in which I worked never used Git. That means I started learning Git on my own at home. This turned into a confusing and frustrating experience because as I tried to learn Git from different online sources and even a couple of books, I noticed a lot of conflicting information. No one seemed to be able to agree what terms to use or what certain terms meant. Turning to more official sources, it didn't get any better. Actually, sometimes it was worse.

I decided to figure out what exact Git terminology is and where things went wrong -- my glossary was born. My glossary is not meant to replace the Git documentation in any way, but to supplement it.

Pulling information from the official Git glossary, man pages, and Pro Git (the book distributed by the Git website for beginners), I realized some things that I'd never seen written down anywhere else. For instance, the term remote reference has two differing definitions, branch has five definitions, and in my detailed version of the definition of tag, I explain that I could never find any clear definition of tag.

The terms remote and tracking were the most challenging. They were so poorly defined and so poorly documented by Git that not only do they have glossary entries, but I wrote complete and highly detailed articles about them. (Links to the articles can be found in the glossary entries.)

Here are my two main links:

• Glossary -- This is the beginning of the glossary. Under the table of contents, you can pick the term you want. Some terms have a link for "More Details" that goes into more detail about the chosen term.
• Introduction -- This index.html file gives a link to the glossary plus the four articles that I wrote about Git terminology. It also states my target audience, where I pull most of my information from, which creative common license I use, and one or two other things.

I'd like your feedback: if you know Git well, I'd like to know if I've gone completely off the rails. If you're a casual user of Git, I'd like to know if the glossary is helpful or confusing.

Expect a few rough spots, though. The glossary is still a work in progress. There are typos, terminology that I should probably add (suggestions are welcome), and a few things that are "half baked" (although I think you'll recognize them when you see them). Nevertheless, there should be plenty enough to get a feel for what I'm trying to do.

One other thing that might interest you: The entire thing is written in html and css. There is no javascript. That means no tracking, and the files are small for the large amount of info given.

Original Submission

1. "Common Joe" - mailto:common.joe.0101NO@SPAMgmail.com
2. "remote reference" - https://commonjoe.gitlab.io/git-clarification/Glossary/index.html#def_remote_reference
3. "branch" - https://commonjoe.gitlab.io/git-clarification/Glossary/index.html#def_branch
4. "tag" - https://commonjoe.gitlab.io/git-clarification/Glossary/defTag.html
5. "remote" - https://commonjoe.gitlab.io/git-clarification/Glossary/index.html#def_remote
6. "tracking" - https://commonjoe.gitlab.io/git-clarification/Glossary/index.html#def_tracking
7. "Glossary" - https://commonjoe.gitlab.io/git-clarification/Glossary/index.html
8. "Introduction" - https://commonjoe.gitlab.io/git-clarification/index.html
9. "Original Submission" - https://soylentnews.org/submit.pl?op=viewsub&subid=50811

printed from SoylentNews, Personal Project That Needs Feedback: A New (Supplemental) Git Glossary on 2024-04-19 17:40:36