SoylentNews is people
SoylentNews
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.
(Score: 0) by Anonymous Coward on Sunday August 22 2021, @12:15PM (12 children)
The git documentation always seemed sketchy to me, and while I was able to get through some of it, tags and branches always seemed to run into cornercases especially in the old days. I mostly haven't been doing advanced activities with with git in the years since as my code development has waned, but this looks to be a good read wen I have more time to do more than skim.
P.S. Thank you very much for keeping to CSS and HTML. I am getting tired of every site and web page requiring javascript just to read the static elements, nevermind the dynamic ones. It gets quite tiring having my browser lag from all the crap javascript running in the background and sucking up memory.
(Score: 1, Informative) by Anonymous Coward on Sunday August 22 2021, @12:23PM (4 children)
This.... and those youtube videos that say they explain a thing, so you have to watch the whole thing to learn that the info you're looking for isn't in them.
(Score: -1, Flamebait) by Anonymous Coward on Sunday August 22 2021, @05:03PM
That's all youtube videos. They're just a vehicle for "personalities".
(Score: 2) by Lester on Monday August 23 2021, @07:28AM (2 children)
Yeah. People seem to have forgotten how to read.
A web page with a few screenshots can be skimmed in a minute, so you find the point where the information you are looking for is. With a video you must go through 10 minutes to reach the same point... if it has ever been there.
And I really don't think that making a video requires less effort than a web page.
(Score: 0) by Anonymous Coward on Monday August 23 2021, @01:14PM (1 child)
This is where you're wrong. Video is an opportunity for the duckspeaking social idiots to social duckspeak to other duckspeaking social idiots, all of whom have no depth of understanding of the topic. It requires way less effort than learning the topic in the amount of detail required to commit something to writing.
You might think you'd at least need an outline or a script to make a video? Nope lol! You just put your smrtfone on a selfie stick and hit record and duckspeak your superficial rituals at the camera, then hit upload. Only takes a few more seconds to upload, and saving time is important in today's increasingly increasing world.
I might just be jaded because I'm trying to learn Blender and Unity to make a VRChat avatar, and I am going to scream if I watch one more video that goes, "Check this box and this box, no idea what these do lol, but it doesn't work without these checked."
(Score: 2) by Common Joe on Monday August 23 2021, @02:09PM
I'll say this: The big glossary page I made took a tremendous amount of my time. I wouldn't be surprised if I spent nearly 50 man hours just to create all the links on that one page alone. I'm not talking about layout or deciding how to better word something. I'm talking about literally deciding which word gets linked, typing <a href="blahblahblah">Something</a>, and verifying it opened up to the proper term. (I usually did that after I already typed in what I wanted to say for a term. I'd put links in for a single term all at once.)
I knew either I put in the work, or the reader would put in work to hunt down the proper link. I decided to make it convenient for the reader. (Believe me, it was mind numbing work.)
(Score: 5, Informative) by Common Joe on Sunday August 22 2021, @12:25PM (3 children)
It is sketchy. I tried hard to iron out corner cases with some creativity, but there are places where there are gaping holes in the original documentation. No amount of creativity on my part can fix that. However, I think I got tags and branches pretty well ironed out. It was not obvious, though. The extra detail I wrote about tags shows why original documentation looks so sketchy.
And yeah, I think one of the best parts about my glossary is keeping it pure HTML/CSS. If this ever takes off, I'd like to be an example / reminder of what people can do without the unnecessary fluff.
(Score: 1, Informative) by Anonymous Coward on Sunday August 22 2021, @01:42PM (2 children)
In common with a lot of new/emerging/recent technologies.
This glossary is useful. It's doing some of the most important work in computer science : putting (the right) names on things.
If nothing else it will help clarify what people mean when they talk about things.
(Score: 2, Interesting) by Anonymous Coward on Sunday August 22 2021, @03:33PM (1 child)
It's been around for more than 16 years. That is definitely NOT new/emerging/recent tech.
There's obviously a serious impedence missmatch between git and what most projects actually need or these problems would have been sorted out long ago.
Git was supposed to be a replacement for the closed source version control software Linus was using. As such, it obviously suffers from the Second System effect.
https://en.m.wikipedia.org/wiki/Second_system_effect [wikipedia.org]
(Score: 3, Interesting) by weilawei on Sunday August 22 2021, @05:26PM
The problem is that people expect CVS, and get git.
Git is far more flexible, and allows you to pick the type of workflow you need, distributed or not. Most people want it to support only the centralized workflow promoted by GitHub, and don't understand why it does anything else. To them, this is bad and confusing.
To anyone who actually learns which parts of it are what internally, it's fairly easy to identify which parts you need to make use of, in which ways.
The former is the Windows philosophy. The latter is the UNIX philosophy.
(Score: 2) by FatPhil on Sunday August 22 2021, @05:20PM (1 child)
As a quick test of sanity, see what "check out" means to different VCSs. Conclusion - no powerful-enough-to-be-useful VCS is sane.
Great minds discuss ideas; average minds discuss events; small minds discuss people; the smallest discuss themselves
(Score: 2) by Common Joe on Sunday August 22 2021, @05:27PM
"Check out" is a good term that I hadn't thought to add to the glossary because the term is so different in Git compared to the other VCSs. I'll give some thought about if I should add it and how to add it.
I'd love to find time to add a section that deals with the Git commands themselves (and ties into the glossary I've made). Something would definitely have to be written about "git checkout" at that point.
(Score: 0) by Anonymous Coward on Monday August 23 2021, @07:10PM
Get noscript or some similar JS blocker that lets you temp or permanently allow some scripts while blocking the rest. Usually enabling the domain's own JS is enough, if not then fuck their site! I don't see a simple way past JS though, the overwhelmingly vast majority of users have it enabled so there is no negative feedback for making your browser build the site.