From 01e644c262769bc40ae783c6e458d84614d31c37 Mon Sep 17 00:00:00 2001 From: Razvan Deaconescu Date: Sat, 23 Sep 2023 15:45:14 +0300 Subject: [PATCH] infrastructure/overview: Fill contents Update contents for introduction section to the "Support Infrastructure" chapter. Signed-off-by: Razvan Deaconescu --- .../infrastructure/overview/reading/read.md | 120 +++++++++--------- 1 file changed, 60 insertions(+), 60 deletions(-) diff --git a/chapters/infrastructure/overview/reading/read.md b/chapters/infrastructure/overview/reading/read.md index b38c3e9..697ecdf 100644 --- a/chapters/infrastructure/overview/reading/read.md +++ b/chapters/infrastructure/overview/reading/read.md @@ -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