This Github repo is a folk of the Ultra Essentials Project developed by the DigEd (Digital Education) team at Cardiff University. The original project was developed with Xerte and published at Ultra Essentials. The aim of this folk is to see if we can use Git and Github as an alternative solution to improve the current workflow.
With that in mind, there are a few objectives I'd like to achieve:
- To make the project more accessible to the DigEd team as well as the wider community of learning technologists and educators.
- To take advantages of Git and Github such as branches, version control, issue tracking, and pull requests to enhance the current workflow.
- To use static site generator such as MkDocs to publish the changes automatically. Here is an example of what the published project looks like: https://dandange8005.github.io/ultra-essentials/.
One of the aims of this project is to introduce a new workflow that encourages collaboration, contributions, and version control for resource development and documentation. By using Git and Github, we are hoping to implement a system for team members and external contributors to suggest edits, improvements, and additions to the resources.
Contributions from within the organisation and outside the organisation are welcome. The following steps are recommended for contributing to the project.
Different ways of contributing to the project:
- Raise an issue
- Request to be a contributor (link to a form) (within the team)
- Fork the repository (outside the team)
For more information on how to contribute to the project, please see the contribution guidelines for this project.
Though Xerte is a great tool for creating online resources, it is not ideal for creating collaborative documentations. It also creates a lot of barriers when it comes to ownership, version control, and collaboration.
Here are some of the challenges we have identified:
- Xerte is not a dedicated content management system
- There is no version control in Xerte
- Xerte doesn't support collaboration in a way that is easy to work out who has updated what
- Lacking comprehensive search function
- Doesn't support localisation nativly
- Xerte Bootstrap template doesn't support multi-level navigation
When we think about version control, we often think about software development. However, version control can be used for any type of project that involves multiple people working on the same files. It is a great way to keep track of changes and to collaborate with others.
Benefits of using Git and Github:
- Version control
- Collaboration
- Issue tracking
- Branching
- Community
There are many resources available for learning Git and Github. Here are a few that we recommend:
- Github Guides
- Git Handbook
- Learn Git
- Learn Git with Bitbucket Cloud
- Version Control with Git
- Learn Git Branching - most visual and interactive way to learn Git on the web
- Git Immersion - a guided tour that walks through the fundamentals of Git
- Sourcetree - a free Git GUI client for Windows and Mac
- GitHub Desktop - a free Git GUI client for Windows and Mac developed by Github
- Visual Studio Code - a free code editor that provides Git integration
- Command Line Interface (CLI) - Git is a command line tool so you can use it from the command line. If you are using Windows, you can use Git Bash which is a command line tool that provides a Bash shell. If you are using Mac, you can use the Terminal app which is a command line tool that provides a Bash shell.
You may have noticed that the project has also been published to https://dandange8005.github.io/ultra-essentials/ which is a documentation site hosted on Github. It uses a tool called MKDocs to help with generating the site from the files that are stored in markdown format.
MkDocs is a static site generator that allows you to create a website from a set of markdown files. It is a Python-based tool that is easy to use and configure. It also provides a number of themes and plugins to customise the look and feel of the website.
For more information on MkDocs, please see the user guide.
Material for MkDocs is a theme for MkDocs that is based on the Material Design guidelines. It provides a clean and modern look and feel for your documentation. It also provides a number of features such as a search bar, a table of contents, and a sidebar.
Benefits of using Material for MkDocs:
- Documentation
- Clean and modern look and feel
- Responsive design
- Search bar
- Automatic table of contents
- Dynamic navigation
- Customisable
- Easy to use and configure
- Markdown syntax
- localisation
- Accessibility
- Free and open source
For more information on Material for MkDocs, please see the documentation.