In DigEd team, we often required to create documentations or guides for different purposes. In a recent project, we were tasked to create an online resource to help staff to move over to Blackboard Ultra courses. We ended up creating the resource in Xerte which is a resource development tool for educators.
It was okay to use Xerte but there are some limitations:
- Xerte is not easy to collaborate with other team members
- There is no version control
- The search function is not great
Though Xerte is a great tool for creating online resources, it is not ideal for creating documentations. Xerte doesn't come with a lot of features that are essential for creating documentations.
For example, Xerte doesn't support Markdown syntax, it doesn't support version control, it doesn't support collaboration, it doesn't support search, etc.
- Xerte doesn't support Markdown syntax
- Xerte doesn't support version control
- Xerte doesn't support collaboration in a way that is easy to know who is working on what
- Xerte doesn't support search
- Xerte doesn't support localisation nativly
- Xerte Bootstrap template doesn't support multi-level navigation
Github + MKDocs + Material for MKDocs
Idealy, we'd like to create a documentation/knowledge base site that is easy to maintain, easy to update, easy to collaborate, and easy to publish.
Below are some of the benefits of creating a project like this:
- Write the documentation in simply Markdown syntax (let you focus on writing the content not the style)
- Create a beatiful documentation site built with MKDocs and Material for MKDocs
- running a local server to test, preview the docs
- Github integration
- version control
- collaboration
- track issues
- Github Codespace
- doc deployed to Github pages and rendered with mkdocs + material for mkdocs theme
- changes made locally or remotely all get published to the Github pages
- lots of great features from Material for MKDocs
I haven't started learning to use Git and GitHub until very recently. Here are some of the notes I took when I was learning Git and GitHub.
There are many benefits of using GitHub to host my notes and here are some of them:
- I don't need to worry about the losing of my notes as they are not just saved on my local computer, they are synched with the GitHub repo.
- I take advantages of GitHub to versioning my notes.
- I am able to work on my notes on multiple computers.
- I can collaborate with others on the same notes.
- I can publish my notes to the public.
- I can use GitHub to host my notes for free.