-
Notifications
You must be signed in to change notification settings - Fork 10
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
infrastructure/overview: Fill contents
Update contents for introduction section to the "Support Infrastructure" chapter. Signed-off-by: Razvan Deaconescu <[email protected]>
- Loading branch information
Showing
1 changed file
with
60 additions
and
60 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,62 +1,62 @@ | ||
| # Support Infrastructure | ||
|
|
||
| Owner: Sergiu Weisz | ||
| Reviewer: Vlad Năstase | ||
|
|
||
| Present infrastructure components: | ||
|
|
||
| - Using GitHub for collaborative editing | ||
| - Tools for generating content (media, slides, post-processing) | ||
| - Component (OpenEdu builder) for building and publishing content | ||
| - Component (`vmchecker`) for automatic submission checking | ||
| - Components to create and present quizzes | ||
| - Using linters to validate content (Markdown, code, configuration files) | ||
| - Integrating linters and deployment / publishing rules in GitHub (as GitHub workflows) | ||
| - Digital rewards | ||
| - Communication specific to the content (Discord channel, GitHub discussions, mailing list) | ||
|
|
||
| This chapter describes the various technologies used to develop, store, deploy and publish the educational content. | ||
|
|
||
| ## Third-Party (Open) Tools Employed | ||
|
|
||
| As part of content development, delivery and consumption, third-party tools will be used to enhance the educator or learner experience. | ||
|
|
||
| Common examples for tools that projects integrate into their workflows: | ||
|
|
||
| - file converters | ||
| - file generators | ||
| - content compilers | ||
| - content deployment workflows | ||
|
|
||
| ## When Should You use a Third-Party Tool? | ||
|
|
||
| - you need to automate a process | ||
| - you need external functionality that has already been implemented | ||
| - you need to scale out a class use case that can only be done with mature tools | ||
|
|
||
| ## What to Look for in an Open Source Project | ||
|
|
||
| When choosing a tool to be employed during any phase of the class lifecycle, one has to mind the following factors: | ||
|
|
||
| - community involvement in product development | ||
| - development history | ||
| - adoption from other parties or institutions | ||
| - success stories with regards to use cases that are compatible with yours | ||
|
|
||
| Open source projects depend on the community to move forward the design and development and goals, based on a stated common use case. | ||
| The more community support a project has, the better the odds that it will be a long lived, well rounded solution. | ||
|
|
||
| Open source projects can be easily tracked using issue trackers, and versioning systems to determine the maturity of the code base. | ||
| Sporadic work on a project or a small person development team mean that the tool will be slow to integrate new features or to do bug fixing work. | ||
|
|
||
| Institutional support for a software solution makes it so there is financial interest in developing the software. | ||
| If a company or institution's financial outcome depends on a project, there will be more development or funding interest from this company. | ||
| For example, when Meta has chosen to use a certain file deployment solution, it was likely for more bugs to be reported and fixed. | ||
|
|
||
| Sections: | ||
|
|
||
| - [Collaboration](../../collaboration/reading/read.md) | ||
| - [Processing](../../processing/reading/read.md) | ||
| - [Validators and Checkers](../../checkers/reading/read.md) | ||
| - [Linters](../../linters/reading/read.md) | ||
| - [Digital Rewards](../../digital-rewards/reading/read.md) | ||
| All actions part of the methodology rest on the support infrastructure. | ||
| The support infrastructure is a loosely-knit set of tools and components that enable, improve or automate various actions related to educational content: development, contributions, publishing, evaluation, delivery, use. | ||
| Components are either preexisting (such as [GitHub](https://github.com) or [`reveal-md`](https://github.com/webpro/reveal-md)) or developed as part of the Open Education Hub initiative (such as [`openedu-builder`](https://github.com/open-education-hub/openedu-builder) or [`vmchecker`](https://github.com/open-education-hub/vmchecker-next)). | ||
|
|
||
| The current infrastructure components are listed below, together with roles and actions related to them: | ||
|
|
||
| - [Git](https://git-scm.com/) is being used as the source code management tool. | ||
| This is used for versioned storage of content, mostly text (Markdown) and snippets (code). | ||
| Git is used for content development and content management. | ||
|
|
||
| - Git is used as part of the [GitHub](https://github.com/) platform, the de-facto collaborative environment for open source / content development. | ||
| GitHub is essential for collaborative work, allowing submissions of contributions via pull requests, issue tracking, discussions, workflow automation. | ||
| Content is stored as GitHub repositories. | ||
| It is used for content contribution and content management. | ||
|
|
||
| - [GitHub Actions](https://github.com/features/actions) are a feature of GitHub that allows workflow automation. | ||
| This is used as part of linting, checking and deployment workflows. | ||
| It is used in content development and content delivery actions. | ||
|
|
||
| - [`reveal-md`](https://github.com/webpro/reveal-md), [`markdownpp`](https://github.com/amyreese/markdown-pp), [`ffmpeg`](https://ffmpeg.org/) are open source tools used to generate content in the corresponding format. | ||
| [`quiz-manager`](https://github.com/systems-cs-pub-ro/quiz-manager) is a tool developed part of Open Education Hub to convert questions in appropriate formats. | ||
| The initial content is generally text / ASCII or SVG. | ||
| The output content is HTML, PDF, XML or image / video files to be presented to the user. | ||
| The aforementioned tools are used during content development, to validate content, and in content publishing and delivery. | ||
|
|
||
| - Linters are used to validate content and ensure it obeys the best practices and that it is consistent throughout the repository. | ||
| While primarily used for source code, linters are also used for Markdown, configuration files, commits and as spellcheckers. | ||
| Linters are typically integrated in automated GitHub Actions workflows. | ||
| They are used during content development and for contributions. | ||
|
|
||
| - [`openedu-builder`](https://github.com/open-education-hub/openedu-builder) is a component developed part of Open Education Hub to automate the publishing of a repository content as a website. | ||
| Generally, `openedu-builder` is invoked automatically as the publishing workflow part of GitHub Actions. | ||
| It can, however, be used manually, to test changes. | ||
| It is the prime tool used during content publishing. | ||
| Published content is then used and consumed directly by educators and learners. | ||
|
|
||
| - [`vmchecker`](https://github.com/open-education-hub/vmchecker-next) is a component developed part of Open Education Hub to automate the evaluation of drills, projects and assignments. | ||
| It relieves educators from the repetitive task of verification, leaving them with tasks of creating content and the checkers for drills. | ||
| `vmchecker` is used as part of evaluation actions and for self-study. | ||
|
|
||
| - [`Moodle`](https://moodle.org/) and [`SmileyTutor`](https://tutor-web.net/) are tools and platforms that can host evaluation items such as quizzes. | ||
| Content is deployed on these platforms by educators and then they are accessed by learners. | ||
| They are used as part of evaluation actions and for self-study. | ||
|
|
||
| - Digital rewards, in the form of the [SmileyCoin cryptocurrency](https://smileyco.in/), are used to incentivize learners to take part in educational activities and to contribute. | ||
| While their fiat worth is reduced, SmileyCoin cryptocurrency can be used as a way to gain educational benefits or as a portfolio of achievements. | ||
| Digital rewards are used part of evaluation actions and for contributions. | ||
|
|
||
| - Communication channels to discuss issues or proposals are essential in creating a community around a repository. | ||
| Any type of communication channel can be used. | ||
| What we recommend, given our experience at Open Education Hub, are the use of a [Discord](https://discord.com/) server, the use of [GitHub discussions](https://github.com/features/discussions), or any collabortive chat, forum or mailing list software. | ||
| They are used as part of content development, content management and contributions. | ||
|
|
||
| The above components are detailed in the corresponding sections: | ||
|
|
||
| - [Collaboration](../../collaboration/reading/read.md) details Git, GitHub, communication channels | ||
| - [Processing](../../processing/reading/read.md) details `openedu-builder` and the corresponding GitHub Actions workflows | ||
| - [Validators and Checkers](../../checkers/reading/read.md) details `vmchecker` | ||
| - [Linters](../../linters/reading/read.md) details linters and the corresponding GitHub Actions workflows | ||
| - [Digital Rewards](../../digital-rewards/reading/read.md) details SmileyCoin / digital rewards |