Stories
Slash Boxes
Comments

SoylentNews is people

posted by janrinok on Sunday August 22 2021, @11:42AM   Printer-friendly
from the Common-Things-That-Aren't-Common dept.

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

 
This discussion has been archived. No new comments can be posted.
Display Options Threshold/Breakthrough Mark All as Read Mark All as Unread
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
  • (Score: 3, Interesting) by Anonymous Coward on Sunday August 22 2021, @12:24PM (1 child)

    by Anonymous Coward on Sunday August 22 2021, @12:24PM (#1169574)

    Definition, Formal:
    An index or pointer that points to collection of staged files (stored in the staging area) that will probably later be committed to the local repository; The staging index is part of the staging area

    An index is an order list of pointers, list of columns with associated pointers...
    A pointer is simple "tag" or "reference" to a single item. Where an item is a row, index,....

    And just a pointer points. But that is using the same term to define the term.

    "staging part is part of staging area". Very helpful??
    A structure reffer to as "staging area" contains a pointer referred to by "staging part" that points to... Better??

    META Issue: A term being used in way that does not fit the universal meaning of the term, then clearly show / define the difference.

    Again back to "index":
    1) an array of pointers, in a given order.
    2) a free standing table with a list of pointers in a given order
    3) an ordered table refering to and is made from a data table, continaing columns from and pointer original row in data table.

    IF you are creating to give clarity. Then please give clarity. So terms based on true dictionary meaning, The show how this term is liek or not like true meanings.

    PS: even dictoionaries this last part wrong. Beucase they assume you have learned fundimental concepts. I once looked the word "two" --> "one more than one". Then looked up "one" --> "unity". Then looked up "unity" --> "one". loops forever.

    Starting Score:    0  points
    Moderation   +3  
       Interesting=2, Underrated=1, Total=3
    Extra 'Interesting' Modifier   0  

    Total Score:   3  
  • (Score: 3, Interesting) by Common Joe on Sunday August 22 2021, @12:39PM

    by Common Joe (33) <{common.joe.0101} {at} {gmail.com}> on Sunday August 22 2021, @12:39PM (#1169579) Journal

    From my glossary:

    An index or pointer that points to collection of staged files

    Good catch. I've been looking at this stuff for so long, that one escaped me. I'll fix it soon.

    As for the rest of your reply: the original Git terminology (which I tried very hard to stick with and not change) backed me into a wall -- especially with index, staging index, etc. I have an entire article dedicated to this. It becomes difficult to figure out better terminology to use when Git abused the terminology this bad. I started using "pointer" a lot since it didn't seem to be used by Git yet, but I admit it can make what I wrote a bit wonky.

    If someone else has some input about how to better this area, I'm open to suggestions.