Documentation

Open Courses is an open education project with the goal of sharing knowledge related to the Computer Engineering and Electronic Engineering fields through an online platform created, managed and populated by IEEE-HKN students all over the world, following the rules defined in the project manifesto. The target of this platform are computer engineering students and Informatics and Electronic enthusiasts that aim at learning something new in a fast, incremental and well-structured way. The project will be developed using well-known open source solutions to reduce the creation and maintenance costs and exploit collaboration potentialities.

Implementation overview

The project has been designed to be sustainable and easy to manage, based on open source solutions and modern concepts that allows reducing developing and maintainability costs. The whole solution will be based on two main tools:

• Git repositories;
• Statically generated pages.

Each subject’s content will be stored in a Git repository. GitHub is used to manage a repository for each subject, assigning contributors and repository owners with different access levels. This allows to use all the tools specific to software engineering also to this specific topic, allowing to report problems in a repository using the concept of issues, adding new exercises and learning material using the pull-requests, thus allowing an easy review process able to check the correctness of each new added material. Moreover, the use of specific automation tools (such as git hooks) allows to reduce the review effort, using scripts able to report directly the non conformance to the defined repository structure.

The added material can be accessed by the students directly using the git repository. However, to increase the accessibility even to users not able to work with git and also allow a more personalized user interface to present the material, static web pages will be generated for each repository. This concept is widely used on GitHub and known as GitHub Pages. Using statically generated pages highly reduces the maintenance costs and effort compared to a dynamic website. It periodically requiring to regenerate them to be conformant with the repositories content, but avoids to deal with security issues or possible malfunctioning of the dynamically generated pages.

How to contribute?

Everyone is free to contribute to the project adding new material, following a new course or just modifying or providing feedback on an already present course.

The contributions will be managed using GitHub. There are three general cases:

• Add or modify material on an already present course: this must be done by means of pull-requests, an easy way to contribute to a GitHub repository. To open a pull-request you need first to fork the course repository in your GitHub account, clone it on your local computer to make the modifications, push them to your fork and from them make the pull-request. When you are opening the pull-request please specify exactly the goal of your work, following the contribution template present in the repository.
• Provide feedback and open a discussion on an already present course: if you want to discuss an exercise or the content of course you should open an issue in that specific course repository. When writing the issue you should follow the issue template provided in the repository, to make sure you target all the informations needed to make a constructive discussion.
• Start a new course: to start a new course you should discuss it with the project maintainers using the dedicated slack channel. You can access the slack channel at opencourses.slack.com, where we will have a channel for each course and a generic channel to make general discussions on the project.

Course structure

Each course should be structured according to the following file list:

• README.md: An introduction to the course, explaining its goal and its structure.
• CONTRIBUTORS.md: A generic file shared by each course in the project to explain how to contribute.
• course.json: contains parsable informations on the course (i.e., name, short description)
• LICENCE.md: The MIT licence.
• requirements.md: The requirements needed to run the exercises (for example the IDE that should be used, the dependencies that must be installed, etc).
• exercises.md: an autogenerated file containing a list of all the exercises.
• open-courses.node: a script shared between all course repositories used to manage the project and exercises;
• exercises/: a folder containing all the other exercises folders
• exercises/exercise_#
• exercise.json: file parsable informations on the exercise contenente key value pair dell’esercizio
• README.md: auto generated from the open-courses.node based on the content of exercise.json
• Other exercises files and support files (such as test to run the exercise, etc)

How to manage contributions?

Most of the maintainers’ work is related to periodical verification of the system status, considering the courses material available, the consistency of the exercises, the correct generation of the supporting files and the static web pages.

Whenever a new contribution is submitted using pull requests, the system should automatically analyze the related data thus enabling automatic characterization and management of the contribution itself.

Contributions must be reviewed to check: associated tags are relevant; format is compliant; content doesn’t contain vulgarity etc; it adds something new and valuable to the repository

Some of these tasks can be carried on automatically: format verification; content semantic control;

but all the others related to semantic analysis still require user intervention, until more advanced scripts will be made. If you want to contribute to this part, we have a slack channel also for that.

Even though static web pages are automatically generated, the page layout, the displayed content order, the connecting paragraphs and so on should be evaluated by a human to detect possible conflicts, typos, errors and so on.

A private index of the whole forest of repositories should also be kept and updated accordingly by maintainers, so that it’s always easy to get access to the courses overview, the new contributions, the revised ones and so on; it’s a kind of “update map” to keep track of the project evolution in time.