Commit 80ea4a52 authored by Johan Richer's avatar Johan Richer
Browse files

Merge 2 FAQ repos

parent 0c2e8686
Pipeline #285 failed with stages
in 1 minute and 21 seconds
module.exports = {
title: 'GitLab Documentation',
description: 'Documentation for the Digital Transport Resource Center',
base: '/gitlab-doc/',
themeConfig: {
sidebar: [
sidebarDepth: 1,
repo: '',
docsDir: '.',
editLinks: true,
editLinkText: 'Éditer sur GitLab',
nav: [
{text: 'DT4A', link: ''},
{text: 'Resource Center', link: ''},
lastUpdated: 'Dernière mise à jour',
![Build Status](
Example [VuePress][project] website using GitLab Pages.
Learn more about GitLab Pages at and the official
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
**Table of Contents** *generated with [DocToc](*
- [GitLab CI](#gitlab-ci)
- [Building locally](#building-locally)
- [GitLab User or Group Pages](#gitlab-user-or-group-pages)
- [Did you fork this project?](#did-you-fork-this-project)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## GitLab CI
This project's static Pages are built by [GitLab CI][ci], following the steps
defined in [`.gitlab-ci.yml`](.gitlab-ci.yml):
image: node:9.11.1
- node_modules/
- yarn install
- yarn build
- public
- master
This sets up a `node9.11.1` environment, then uses `yarn install` to install dependencies and `yarn build` to build out the website to the `./public` directory.
It also caches the `node_modules` directory to speed up subsequent builds.
## Building locally
This project uses [yarn](, you'll need to install this globally before you can get started.
npm install -g yarn
Then you need to install the project dependencies:
yarn install
Now you're ready to go.
To run the local dev server just use the following command:
yarn start
Your website should be available at [http://localhost:8080/vuepress]
*Read more at VuePress' [documentation][].*
## GitLab User or Group Pages
To use this project as your user/group website, you will need one additional
step: just rename your project to ``, where `namespace` is
your `username` or `groupname`. This can be done by navigating to your
project's **Settings**.
Read more about [user/group Pages][userpages] and [project Pages][projpages].
## Project name
You'll need to set the correct base in docs/.vuepress/config.js.
If you are deploying to https://<USERNAME or GROUP>, you can omit base as it defaults to "/".
If you are deploying to https://<USERNAME or GROUP><REPO>/, (i.e. your repository is at<USERNAME>/<REPO>), set base to "/<REPO>/".
## Did you fork this project?
If you forked this project for your own use, please go to your project's
**Settings** and remove the forking relationship, which won't be necessary
unless you want to contribute back to the upstream project.
Forked from @samdbeckham
# Documentation for the Digital Transport Resource Center
# Data FAQ
Here are some of the most Frequently Asked Questions about data on [Digital Transport for Africa]( (DT4A). Feel free to [ask new questions](!
## What's data?
**Data are just files on your computer**: documents, spreadsheets, images... A dataset is a collection of data, sometimes multiple files in a compressed ZIP file (`.zip`), sometimes multiple sheets in an Excel file or a even a single CSV file (`.csv`) with multiple column.
[GTFS]( (also known as GTFS-Static, not to be confused with GTFS-RT) is a common format to share public transit data. It's a ZIP file (``) containing text files (`.txt`) with [comma-separated values](
## What's open data?
Open data is data that is been shared in a way that others have the rights to use and republish it. You do this by sharing your data with an open data license (e.g. [CC0]( or [ODbL]( Without a license, nobody knows if they can use this data: it's not open.
## What's Gitlab?
The DT4A project provides a platform to upload, publish and share data, accessible here: []( It's an instance of the open source tool called Gitlab. Gitlab is the open source equivalent of [Github]( DT4A's Gitlab is not to be confused with []( Both are independent and separate websites.
For the sake of simplicity, we call "Gitlab" or "Resource Center" the website at It looks like this:
## How to register on Gitlab?
In order to have to access to most features on Gitlab, such as uploading data, you will need to register a personal account. To do so, [click here]( and complete the Register form:
You can also directly sign in with a user account on or, if you already have one there, at the bottom of the page.
If you've successfuly registered an account and logged in, you'll see your username by clicking on the menu at top right corner:
## How to upload data?
First, please [register an account on Gitlab](#how-to-register-on-gitlab) if you haven't done so already.
When you're logged in as a user, you can create a "Project", which is a repository where you will be able to deposit files. To do so, click on [New project]( at the top of the page:
1. Enter a project name, for example the name of the city if you want to upload a GTFS dataset for that location;
2. Select "Initialize repository with a README";
3. Click on "Create project" (leave the rest as is):
Congratulations, you have created your first repository! It looks something like this:
You can now start **uploading** files in this repository, to do so click on the + menu then "Upload file":
An "Upload New File" menu will appear
1. "Click to upload" then find the file you want to upload from your computer;
2. Write a comment to describe your action (also called a "commit");
3. Click on "Upload file":
Congratulations, you have uploaded your first bit of data!
You can share this link with everyone now on the Internet now.
## How to add a license?
_Coming soon_
## How to create a new file?
On Gitlab you can create a file directly within the interface, for example to write new documentation. To do so, go to your repository where you want to create a new file, click on the + menu then "New file":
1. Add your text;
2. Add a filename (for example ``);
3. Write a comment to describe your action (also called a "commit");
4. When you're finished, click on "Commit changes" at the bottom:
## How to edit a document?
On Gitlab you edit text files directly within the interface, for example to edit existing documentation. To do so, go to your repository where you want to edit a file and click on the file:
Then click on the "Edit" button:
Modify the text, write a "commit message" to describe your action and when you're finished, click on "Commit changes" at the bottom.
## How to document my data? What's Markdown?
On Gitlab, each repository can be documented by creating a text file called a "README". It will be displayed by default when you access the repository's page, so it's pretty useful to have one!
It's best to format the README using Markdown. A Markdown document is just a basic text file ending with `.md`, and using some simple formating. If you're not familiar with it, please take a look at [this guide](, or read [the Wikipedia article about it](
To document your data, create a file named `` or edit it if you already have one in your repository. (See How to create a new file? and How to edit a document?)
## What's a "project"? What are "groups"?
In Gitlab, a "project" is a repository (or "repo") where users can deposit files; a bit like a folder on your computer. Each project is managed by one or several users who have rights on it. A "group" is just a folder to bundle several repositories together.
New users with basic access can only create projects in their own username group, whereas administrators can create new public groups and do many other things to organize the Gitlab platform.
## How is Gitlab organized?
As part of DT4A, Gitlab is jointly administered by [AFD]( and [WRI](, who make decisions on the way it is organized and managed.
Once [you've registered](#how-to-register-on-gitlab), your account on Gitlab has the lowest level of permissions. Further access & permissions can be given to you by administrators according to your status.
Gitlab repositories are categorized in several [public groups](
If you want to a repository you've created to one public group, please contact an administrator.
# Documentation FAQ
Here are some of the most Frequently Asked Questions about documentation for [Digital Transport for Africa]( Feel free to [ask new questions](!
## What's a documentation?
Documentation is just a way to help other people understand something that you did, and learn from it. To do that, we propose that you use [Gitbook](
## What's Gitbook?
Gitbook is a popular tool that "makes it easy to write and maintain high-quality documentation". Technically, it's a piece of software which is both [open source]( (meaning that you can install it and use it on your own computer or server), and is also available as [a service on](
Basically, **Gitbook takes formated text and transform it into a small website that you can browse like a book** (hence the name).
This way you only have to focus on the essential: the content. Gitbook takes care of the rest for you: formating, making a nice interactive website and all that.
Digital Transport for Africa maintains an instance of [Gitlab]( which allows you to host, publish and share all sorts of resources: code, data, text and [static websites](, which means - you guessed it - that we can host Gitbooks (thanks to [Gitlab Pages]( and [Gitlab CI](
## How does this work? Can you show me an example of a Gitbook hosted on Digital Transport for Africa?
[You can find the basic template here]( What you see is a repository with files in it, the "git" part of the name. It contains mainly the raw content of the documentation: a `README` and a `SUMMARY`.
[Gitlab then deploys this as a small website]( the "book"! The content of the `README` forms the content of the page, while the content of `SUMMARY` makes the left column a table of contents.
Another, more complex example: [git repo]( -> [book]( [Here are other real-world templates to model from](
Note: When you change the content of the git repository, the book is built automatically You don't need to do anything but editing content. Also, the book's domain name ( has to be different than Gitlab's ( for security reasons (cookies and stuff).
## How do I need to format my text?
Just use Markdown: a basic text file ending with `.md`, and some simple formating. If you're not familiar with it, please take a look at [this guide](, or read [the Wikipedia article about it](
## How can I create my own Gitbook?
You don't have to understand the technical details. Here's all that you need to know:
1. Choose a template that you like, such as [the one above](
2. Fork it! Click on the button at the upper right corner. Then, select your space (where the git repo will be copied).
3. Edit the content of the `` (which, by convention, will be the first page of your gitbook) by clicking on it in the list of files, then clicking on "Edit" in the upper right corner.
4. When you're finished, click on "Commit changes" at the bottom.
5. That's it! Your first page is done, and it will now be deployed as your own gitbook. Go find it by opening this URL in your browser: `<your namespace>` (with the namespace being most likely your Gitlab username, the same that appears in the URL of your repository).
Things you can do next:
6. Add other pages to your book by creating other Markdown files: click on "New file"
Then, add your text (just as you did at step 3 above) and don't forget to type a filename ending with `.md`. Rince and repeat for each new page of your book.
7. Don't forget to also update the `` file by adding each new page.
Note: You can also clone the repo locally and edit the files on your computer with your editor of choice, then pushing each changes to the repo.
Please ask questions by creating an issue ticket [here]( or by sending us an [email](
module.exports = {
title: 'GitLab ❤️ VuePress',
description: 'Vue-powered static site generator running on GitLab Pages',
base: '/vuepress/',
dest: 'public'
\ No newline at end of file
home: true
heroImage: /hero.png
- title: Simplicity First
details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
\ No newline at end of file
......@@ -7,8 +7,8 @@
"license": "MIT",
"private": false,
"scripts": {
"start": "vuepress dev docs",
"build": "vuepress build docs"
"start": "vuepress dev",
"build": "vuepress build"
"dependencies": {},
"devDependencies": {
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment