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: 2) by Common Joe on Wednesday August 25 2021, @03:46AM
That's an excellent question. There are several reasons.
First of all, the bulk of the editing work would not be affected by whether I chose a markdown language. Most of the editing work was deciding what words to choose, how to arrange the sentences, deciding when terms should be quoted or linked, etc. The format which markdown would help provide was very trivial compared to the rest of the work. It's not a lot of work to write <p>BlahBlah</p> than it is to hit the enter key twice.
Second, a huge amount of work was adding links. With a good IDE, Markdown does not reduce he amount of work it takes to add links. Often, I would write the information for a term, walk away for a while, come back to the term, edit the information, (repeat walking away and editing again as needed), then add links. The links! That was a lot of boring work. I often thought about how I could automate that, but in the end, there was no good way. I even thought about writing my own markdown language and writing a parser, but even that would have been more work.
Third, the output must always be strictly html. I thought about whether other kinds of output would be advantageous. Splitting the glossary to LaTeX or plain text would rob the glossary of its greatest advantages -- the format and the links. Really, one of the greatest assets of the glossary is the ability to just scroll through the entire glossary, browse, and discover.
Finally, I wrote extra div tags in the html so I could specifically format the glossary with css a particular way. If I chose Sphinx or another output generator, I would have to conform the glossary to another type of formatting. Doing so would rob the glossary of how easy it is to scroll quickly to find what you're looking for. Go look at the output of Python or Java or any other pre-formated output and see if there anything which would compare to what I have. I use font sizes, color contrast, and multiple levels of indent to indicate information. Like an old time paper dictionary, this glossary is built to scroll. There is no way I could create an entry for a term in the glossary with the level of information I provide without those extra div tags. I would have had to write them manually in the markup language... and if I did that, then the markup was really useless to me.
Markup and Sphinx is great for simple stuff. While not obvious, my glossary formatting goes a level beyond that.