This week I’m continuing my quest to become more technical. Today’s post is going to be a bit of a twofer. I am focusing on the popular software development platform GitHub and the lightweight markup language known as Markdown. I’ll briefly outline what they are, why we use them, and why I’m interested in them.
GitHub is a software development platform that is used by 100 million developers around the world today. GitHub exists as a central hub for developers to open, host, and manage their own repositories.
The repositories in GitHub are Git-based. What does that mean? Git is a tool developers use for source code and version management. It utilizes the command line in a way that allows multiple developers to collaborate efficiently when making changes to a project’s source code. I’m sure you can see the correlation here. When you use GitHub, you need to have at least a basic knowledge of Git in order to manage your repository.
Which brings me to today’s post: I’m going to start learning Git. Well, at least enough to function in a technical writer role. By learning Git, I’ll be able to start using GitHub to contribute documentation to open source projects. Which is exciting because this gives me the ability to start building some more technical muscles by working on more technical projects.
How exactly do I contribute to open source projects? Git is only part of it. By learning Git I’ll be able to properly interact with the repositories, but that won’t enable me to contribute to documentation directly. There are multiple ways to contribute documentation to a repository; however, an easy way to contribute is using the language known as Markdown. I pulled this definition of Markdown directly from the Markdown Guide: “Markdown is a lightweight markup language that allows you to add formatting elements to plain text”.
If you’re familiar with HTML at all, then you’ll know that it uses tags to denote different elements. For example, the <h1> tag is used to denote a first level heading in a webpage. In Markdown you use “#” to denote a heading. If you want a smaller heading, say a level three, then use three number signs “###”. Markdown uses this basic syntax so that it is easy to read your text even when the intended format isn’t rendered. It’s quick to learn and has the added bonus that you can open its file using almost any application.
To practice using Markdown, I created a GitHub repository (see, it’s alllll coming together now) and used Markdown to generate my repository’s README file. Below you’ll see the Markdown version of my README.
Even in this format, it’s still easy to read and you can get a feel for the formatting I’m wanting to achieve. Once my changes are committed though, you can see the elements I dictated in the Markdown file come alive.
Cool, huh? It was nice being able to get some practice using Markdown. I plan on using Markdown going forward when writing these blog posts so I can get better at it. Again, it isn’t difficult, but it still takes practice to get the hang of the syntax.
I had fun creating my README file for an example and am looking forward to learning Git in earnest. If you found any of this interesting, I encourage you to do some more research on your own. There’s a lot more beyond what I outlined here. I tried to keep it incredibly high-level for the sake of brevity. As always, thanks for reading!
Monica Dailey 