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 Mojibake Tengu on Sunday August 22 2021, @01:17PM (4 children)
There are at least two git-based matured wiki projects out there: ikiwiki and gitit.
Their difference from "normal" wikis which use database backends is obvious: those above use version control system as backends.
Technically, they are wiki compilers (static generators). That makes doing wikiing things more difficult for normal people but very easy for programmers.
That model benefits both large projects with many people as good principle of distributed documentation and tiny one man projects as good principle of simplest as possible.
It's trivial to integrate wiki documentation into project.
So, instead of pure html/css website you could make your documentation to anything (git including) a full wiki.
https://en.wikipedia.org/wiki/Ikiwiki [wikipedia.org]
http://ikiwiki.info/ [ikiwiki.info]
https://en.wikipedia.org/wiki/Gitit_(software) [wikipedia.org]
https://github.com/jgm/gitit [github.com]
Respect Authorities. Know your social status. Woke responsibly.
(Score: 2) by Common Joe on Sunday August 22 2021, @02:18PM (3 children)
I use Git as I make changes to the glossary and push the changes to GitLab.
I looked at several Markup languages just before I started writing div tags left and right, but they didn't have the power that I was looking for. Nevertheless, I'm unfamiliar with Ikiwiki and Gitit, so I'll take a closer look at them to see if they would helpful or not. Thanks for the tip.
(Score: 2) by bloodnok on Sunday August 22 2021, @06:21PM (2 children)
First off, I think this is great. Good documentation always makes things better.
As for markup languages I tend to use docbook. It's huge and horrible to learn but it has all the power you need, and the rendering engines are eminently hackable.
As a way of getting started, you can use pandoc (https://pandoc.org) to convert from markdown for your initial docbook layout. For me the joy of docbook is in semantic markup. I write what I mean with no concern for rendering and then let the rendering engines turn it into something more beautiful.
I'm not suggesting that you rewrite what you already have, but if you want to get away from caring about the rendering there are worse tools and it might be worth a look. My veil project
https://github.com/marcmunro/veil2 [github.com] uses docbook if you'd like an example with a documented build (see the docs target in GNUmakefile)
__
The major
(Score: 2) by Common Joe on Monday August 23 2021, @12:55AM
Pandoc isn't the right thing for this project, but it looks like a very useful project for other things. I've bookmarked it. Thanks for the tip.
(Score: 2) by hendrikboom on Monday August 23 2021, @02:14AM
Are you familiar with asciidoc? and its new implementation, asciidoctor?