Skip to content

Latest commit

 

History

History
58 lines (40 loc) · 2.75 KB

index.md

File metadata and controls

58 lines (40 loc) · 2.75 KB
Raw

Why the project?

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.

Why Xerte

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

Why NOT Xerte

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

The Solution

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

Github

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.