GitHub is a web-based repository for all kinds of projects. One of the original purposes of GitHub is for coding. However, it is also well suited to any text-based content. If OER (open educational resources) is created in a text-based format, GitHub is, potentially, a great place to host the content.
That’s it! Well, not really. Let us go over the concepts involved.
The term “repository” refers to a resource where:
What does “revision-controlled” mean? It means a lot of things, including the following:
In addition to providing a web-based method to manage repositories, GitHub also offers additional resources. For example, the “Issues” tab of a repository allows others to leave comments. This facilitates a great mechanism for readers/learners to provide feedback. However, “issues” is accessible only to signed-in GitHub users. Considering GitHub is free, this should not deter a reader/learner from signing up and then reporting issues.
If the readership of an OER item is tech-savvy enough, each reader/learner can “fork” the repository, make a suggested change, and then place a “pull request” to update the main branch of the repository where all browsers see. This is a great method for readers and others to contribute and improve the content of a repository.
There are no hard-and-fast rules. If the granularity is too fine, then the author ends up with many repositories. This can make projects difficult to maintain. On the other hand, if the granularity is too coarse, then it is difficult for another person to make only one change to a small part of the project.
At the end of the day, text files are relatively small. If the OER is in book form, then it makes sense that each book has a repository. However, if the OER is in smaller independent modules, then a single repository to host all the modules makes sense.
For others to quickly locate content, it is best not to make the name of a repository too complex. The URL to a single file of a repository contains the author’s account name as well as the name of the repository. Therefore, there is no need to duplicate these components in the name of a file in a repository.
Markdown is essentially a simple, text-only, and intuitive mark up language. Compared to HTML (hypertext markup language), Markdown is much easier to type, less prone to syntax issues, and far more effective as a language to create text (and beyond!) content.
Markdown has many features that make it suitable for text-based content in many domains. For example, it can handle equations like $E=mc^2$. It can also be used to generate simple graphs like the following:
flowchart LR
id1[Node 1]
id2[Node 2]
id1 --> id2
MarkDown can also syntax highlight code blocks:
int main()
{
return 0;
}
Because Markdown is a text-only markup language, any text editor can edit content! GitHub has a decent in-browser editor. It does not have all the fancy spell-check and grammar-check features, however. That being said, it is fairly easy to copy and paste text-only content between fancy desktop editors and the web interface.
Each section is automatically an anchor that a URL can reference. However, you can also additional custom anchor using a little bit of HTML code. The special anchor uses the HTML code <a href="#customanchor">custom anchor</a>.
You can also have multiline derivations:
\[\begin{align} &x+x+x\\ =& 2x+x\\ =& 3x \end{align}\]You can also easily add “special visual sections” in the flow of the main text.
[!NOTE] Salt dissolves faster in hot water.
[!WARNING] This is a warning.
[!TIP] Use a microwave oven to quickly heat up water.
[!CAUTION] The water is hot!
[!IMPORTANT] Don’t pour hot water on yourself!
You can use the <detail> element in HTML. Let’s take a look at the following Markdown/HTML code:
<details>
<summary>Energy equation</summary>
$E=mc^2$
</details>
It is rendered, using GitHub’s web interface, as follows:
There are multiple ways to contribute and/or utilize GitHub-hosted OER content.
First, go to GitHub, click “Sign up” (upper right corner) and create a GitHub account. This step is necessary for all the methods to contribute to the project.
An issue usually refers to a software bug for most GitHub repositories. However, in the context of OER, an issue can be a typo, mistake, inaccuracy, or other items that need to be fixed. Users with a “contributor” role of a GitHub repository can, then, investigate and potentially resolve the issue. When an issue is resolved, it will be marked as such, and the user who originates the issue will be notified.
A discussion differentiates from an issue because a discussion does not reflect something to be fixed. GitHub provides 5 built-in categories of discussions. In the context of OER, this is how each category can be utilized:
Discussions are a great way to contribute to an OER project by talking to the developers and other users of the OER content. Any user can participate.
Users who are comfortable with Markdown can use the edit (writing instrument icon) tool to change the OER content. Any user can fork a public GitHub repository. A fork creates a new branch in the repository, and there can be many revisions and even further forks along this branch.
After each revision, click “Commit Change” so that the revision is tracked along the forked branch. This means the revision does not make it to the MAIN branch for everyone to see. While changes are being made to a forked branch, the MAIN branch can also have its own revisions.
A forked branch can remain forked forever. Typically, however, a forked branch is merged with the main branch once the changes are finalized. This allows the contribution to be shared with the general user base.
When a forked branch is ready to be merged to the MAIN branch, click “Create pull request”. This notifies the owner of a repository about the availability of a forked branch to be merged. In a “pull request,” be descriptive of what the fork is about.
Fork/pull is better than using “Issues.” Fork/pull only needs the manager of the repository to verify the changes before merging to the MAIN branch. This is the most effective way to contribute to OER content. However, unlike the previous approaches, fork/pull does require the contributor to be comfortable editing content in Markdown (or whatever the source language is).
A learner may want to create a fork permanently to incorporate the learner’s own notes and annotations. At the same time, the learner may also want to get the latest updates to the original document. This can be done entirely using the GitHub web interface.
A forked branch is still a part of the original repository. Cloning allows an entire repository to be cloned and has an entirely different team of managers and contributors.
Any GitHub user can import another public repository. To do this, click the + drop-down next to the search bar, then click “Import repository.” Copy and paste the URL of the source repository, and fill in the rest of the form.
<> Code, and then copy the HTTPS. For example, the URL of the repository containing this document is https://github.com/proftak/modules.git.Clone/import is the ultimate expression of “open” in OER. Like the content, but not so much the management of the content? Clone it and manage it yourself!
username or access token.Cloning/importing differentiates from fork/pull because a new repository is created out of the original, and the new repository can belong to a different GitHub user.