I have delivered public talks, but my professional writing has been restricted, because the documentation I created for Altitude Software and for Farfetch was never public. But since today, some of my professional writing is finally public.

I was approached by Bump.sh, a French company that is developing software to publish API references, addressing many of the needs we had at Farfetch:

• Quick publication of beautiful API references, triggered from a Git-based workflow. They have a limited provision to integrate with non-reference documentation, but they already go beyond OpenAPI to support AsyncAPI, and they plan to support more standards.
• Automatic computation of changes and breaking changes. I created a swagger-diff at Farfetch, but we never integrated it into the build to create an automatic change log.

After I understood the strengths of the product and the business positioning of Bump.sh, we agreed on a series of articles, starting with an introduction to Git.

Something that has always bothered me in Git tutorials is how quickly they delve into the command line. Due to the messy nature of Git, graphical tools are different enough from each other, prompting teachers to stick with the command line because it is both neutral and universally available. But that also means that tutorials, eager to teach practical skills, quickly show command-line examples, often within the first 10 lines of the tutorial. I always felt those examples would confuse and alienate beginners.

So, I aimed to explain Git without resorting to the command line. My objective was to write an introduction good enough to motivate beginners to learn more, while giving the same beginners a good basis to pick up their tools and to start using them.

I started by enumerating the major concepts I wanted to teach, with an emphasis on what Git can do for people. I decided to explain file, tree, commit, tag, branch, and pull request. Later, I added merge commit, working directory, remote branch, push, and pull. While writing the article, I felt the need to tell people you can rewrite history with Git, and the dangers of doing so, so I added rebase with squash.

I organized the tutorial in the same way I organize training, by introducing concepts in chunks to limit the cognitive load of readers. For each chunk, I have the definitions, an illustration, and a concrete example.

Does it work? I got some relevant early feedback:

• A non-technical Portuguese family member with a limited command of English learned enough to continue through ProGit on her own. I'm quite proud of this, especially because this family member read the article out of curiosity, without any immediate need to actually use Git.

• A colleague that teaches docs-as-code said that the article was clear and simple. In particular, he did not say the article was too simple to be useful, which was the risk I took.

If you have not done so, I invite you to check for yourself the Primitive Concepts of Git.