Skip to content

Commit

Permalink
Improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
dashdashzako committed Nov 21, 2019
1 parent 8644f2b commit 9a376de
Show file tree
Hide file tree
Showing 2 changed files with 137 additions and 65 deletions.
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@ and this project adheres to

### Changed

- Project documentaton.

### Added

- Markdownlint same heading rules (MD024).

## [v2.0.12] - 2019-11-20
Expand Down
198 changes: 133 additions & 65 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Inria MOOC Digital Accessibility Website
# Inria Digital Accessibility MOOC Website

Inria MOOC Digital Accessibility website is the standalone version of the MOOC
Inria Digital Accessibility MOOC website is the standalone version of the MOOC
that was hosted by [FUN](https://www.fun-mooc.fr/).
It also contains web pages to be embed for 3rd party platforms such as
[FUN](https://www.fun-mooc.fr).
Expand All @@ -11,100 +11,109 @@ quiz.

It is available at the following url: <https://mooc-accessibility.inria.fr/>

## Requirements
## How to Consume this MOOC

This website is generated using [Hugo](https://gohugo.io) `>v0.58.3`.
[Installing Hugo](https://gohugo.io/getting-started/installing) is required in
order to build the static HTML files.
There are two ways to consume this MOOC.

## Development
### Browsing the Website

The only software requirement is Hugo, but if you want to test website locally
you will need to download the
[MOOC player](https://github.com/dashdashzako/aiana-player) assets:
All the MOOC content is served at <https://mooc-accessibility.inria.fr/> and is
free to browse. If you are just looking for plain content consuming, this is
probably what you are looking for.

1. Download Aiana player release zip archive; it should be the same as the one
specified in `PLAYER_VERSION` key in `.travis.yml` file.
Releases are listed on the
[repository releases page](https://github.com/dashdashzako/aiana-player/releases).
### Embeding the MOOC

2. Unzip the archive.
If you host your own website and you want to integrate a MOOC sequence to it,
the recommended way to do it is by using an `iframe`.

3. Move the `release/manifest.yml` file to `data/manifest.yml`.
```html
<iframe
src="https://mooc-accessibility.inria.fr/course/w1-s1/embed.html"
class="mooc-iframe"
scrolling="no"
width="800"
height="546"
/>
```

4. Move the player JavaScript files to `static/js/`.
This integration is better suited when you do not want to host any of the player
files on your servers.

5. Move the `release/locales` folder to `static/`. These files are included in
the player release archive since `v2.2.1`. If you target an earlier version,
the files can be copy pasted from the player repository depending on
targetted player version. For example, if you intend to use `v2.2.0`, you
should download all files from
[`v2.2.0` tree](https://github.com/dashdashzako/aiana-player/tree/v2.2.0/public/locales).
This is how FUN was integreting the MOOC to their platform without having to
bother about configuration or JavaScript integration to their code.

6. Just run `hugo`, or if you specify a specific serving URL,
`hugo --baseUrl https://<hostname>.<ext>/`.
#### Note About Styles

7. Go to `http://localhost:1313`.
To remove the `iframe` borders, you need to explicitely set a CSS rule for it:

## Analytics
```css
.mooc-iframe {
border: 0;
}
```

Two kinds of analytics will be measured as a user browses pages and uses the
MOOC player. Both are optional but may help understanding usages and improve the
website, the MOOC content, and the player.
#### Courtesy of Inria

### Audience Analytics
Remember that when you embed this MOOC to your website, it consumes resources
provided by Inria.

Audience analytics helps understanding global usage of the website and gives
insights about users browsing context: screen resolution, browser, operating
system…
If Inria encourages people to spread this MOOC, it does not charge anything for
this service. So please use it moderately, and be kind to notify us when you
embed it in a MOOC platform.

Inria recommends using [Matomo](https://matomo.org/) (formerly Piwiki) to
collect the analytics, and this website uses the
[Inria on-premise instance](https://piwik.inria.fr/).
### Service-Level Agreement

The Matomo `script` tag will be integrated on each page if a `data/matomo.yml`
file exists and has a `site_id` key.
Inria does not provide any formalized agreements to deliver a particular level
of service, please consider it as a best-effort model.

For a local development environment, content of the file will be:
Unplanned outages and maintenance may happen without any notice, and Inria
cannot guarantee [the MOOC website](https://mooc-accessibility.inria.fr/) uptime
nor performances.

```yaml
site_id: '101'
```
If you plan on embedding the MOOC, you should keep that in mind.

The Matomo identifiers are:
---

- `100` for production
- `101` for staging
## Development

To require access to the website analytics, please contact any of the
administrators:
This website is generated using [Hugo](https://gohugo.io) `>v0.58.3`, which is
the only required software installation.
[Installing Hugo](https://gohugo.io/getting-started/installing) is required in
order to build the static HTML files.

- [Pascal Guitton]([email protected])
- [Julien Lelaurain]([email protected])
To test the website locally, you will also need to download the
[MOOC player](https://github.com/dashdashzako/aiana-player) assets that are not
included to this repository:

### Web Player Events
1. Download Aiana player release zip archive; it should be the same as the one
specified in `PLAYER_VERSION` key in `.travis.yml` file.
Releases are listed on the
[repository releases page](https://github.com/dashdashzako/aiana-player/releases).

Player events help understand how users are interacting with the MOOC content.
They provide extensive details about the player state, but none about the user
triggering them.
2. Unzip the archive.

The events will be pushed to a remote server only if its url is provided. The
logging endpoint can be specified within a `data/logger.yml` file containing a
`url` key.
3. Move the `release/manifest.yml` file to `data/manifest.yml`.

For example, the `data/logger.yml` file could be:
4. Move the player JavaScript files to `static/js/`.

```yaml
url: 'https://domain.com/path/to/write/logs'
```
5. Move the `release/locales` folder to `static/`. These files are included in
the player release archive since `v2.2.1`. If you target an earlier version,
the files can be copy pasted from the player repository depending on
targetted player version. For example, if you intend to use `v2.2.0`, you
should download all files from
[`v2.2.0` tree](https://github.com/dashdashzako/aiana-player/tree/v2.2.0/public/locales).

6. Run `hugo server`. This command will automatically reload the server when
content is modified.

7. Go to `http://localhost:1313`.

## Managing Content

The ["Content Management"](https://gohugo.io/content-management/) section on of
the Hugo documentation explains extensively how to manage content, please refer
to it.
The ["Content Management"](https://gohugo.io/content-management/) section of the
Hugo documentation covers extensively how to manage content.

## Create a Release
## How to Create a Release

[Travis CI](https://travis-ci.com) is used as continuous integration platform.

Expand Down Expand Up @@ -147,6 +156,8 @@ the production environment:
#
# target player tag is v2.2.3.

cd path/to/mooc-accessibility-static

# download player archive
curl -LO https://github.com/dashdashzako/aiana-player/releases/download/v2.2.3/release.zip

Expand Down Expand Up @@ -175,6 +186,63 @@ echo "tag: $(git describe --tags)" >> build/prod/version.html
echo "player: v2.2.3" >> build/prod/version.html
```

---

## MOOC Analytics

Two kinds of analytics will be measured as a users browse pages and use the MOOC
player. Both are optional, though they may help understanding usages and improve
the website, the MOOC content, and the player.

### Audience Analytics

Audience analytics helps understanding global usage of the website and gives
insights about users browsing context: screen resolution, browser, operating
system…

Inria recommends using [Matomo](https://matomo.org/) (formerly Piwiki) to
collect the analytics, and this website uses the
[Inria on-premise instance](https://piwik.inria.fr/).

The Matomo `script` tag will be integrated on each page if a `data/matomo.yml`
file exists and has a `site_id` key.

For a local development environment, content of the file will be:

```yaml
site_id: '101'
```
The Matomo identifiers are:
- `100` for production
- `101` for staging

To require access to the website analytics, please contact any of the
administrators:

- [Pascal Guitton]([email protected])
- [Julien Lelaurain]([email protected])

### Web Player Analytics

Player events help understand how users are interacting with the MOOC content.
They provide extensive details about the player state, but none about the user
triggering them.

Actions made by users will be pushed to a remote server only if its url is
provided. The logging endpoint can be specified within a `data/logger.yml` file
containing a `url` key.

For example, the `data/logger.yml` file could be:

```yaml
url: 'https://domain.com/path/to/write/logs'
```

To know more about web player actions, please refer to
[the player documentation](https://github.com/dashdashzako/aiana-player).

## Code Status

[![Build Status](https://travis-ci.com/dashdashzako/mooc-accessibility-static.svg?branch=master)](https://travis-ci.com/dashdashzako/mooc-accessibility-static)

0 comments on commit 9a376de

Please sign in to comment.