Fixes broken links and adds hands-on exercise

fixes #157

docs/ci/popperci.md

@@ -47,6 +47,34 @@ popper experiment init <name>
 
 Where `<name>` is the name of the experiment to initialize.
 
+<!--
+
+## Special Subfolders
+
+Folders named after a tool (e.g. `docker` or `terraform`) have special 
+meaning. For each of these, tests are executed that check the 
+integrity of the associated files. For example, if we have an 
+experiment that is orchestrated with [Ansible](http://ansible.com), 
+the associated files are stored in an `ansible` folder. When checking 
+the integrity of this experiment, the `ansible` folder is inspected 
+and associated files are checked to see if they are healthy. The 
+following is a list of currently supported folder names and their CI 
+semantics (support for others is in the making):
+
+  * `docker`. An image is created for every `Dockerfile`.
+  * `ansible`. YAML syntax is checked.
+  * `datapackages`. Availability of every dataset is checked.
+  * `vagrant`. Definition of the VM is verified.
+  * `terraform`. Infrastructure configuration files are checked by 
+    running `terraform validate`.
+  * `geni`. Test using the `omni validate` command.
+
+By default, when a check invokes the corresponding tool, PopperCI uses 
+the latest stable version. If another version is required, users can 
+add a `.popper.yml` file to specify this.
+
+-->
+
 ## CI System Configuration
 
 In this section we describe how to configure a CI system so that 
@@ -102,6 +130,14 @@ being executed.
 The following is the list of steps that are verified when validating 
 an experiment:
 
+<!--
+
+ 1. Ensure that every versioned dependency is healthy. For example, 
+    ensure that external repos can be cloned correctly.
+ 2. Check the integrity of every special subfolder (see previous 
+    subsection).
+-->
+
  1. For every experiment, trigger an execution (invoke `setup.sh` 
     followed by `run.sh`).
  2. After the experiment finishes, execute validations on the output 
@@ -150,12 +186,13 @@ file of the experiment.
 
 ## Testing Locally
 
-The [PopperCLI](https://github.com/systemslab/popper/popper) tool 
-includes a `check` subcommand that can be executed to test locally. 
-This subcommand is the same that is executed by the PopperCI service, 
-so the output of its invocation should be, in most cases, the same as 
-the one obtained when PopperCI executes it. This helps in cases where 
-one is testing locally. To execute test locally:
+The 
+[PopperCLI](https://github.com/systemslab/popper/tree/master/popper) 
+tool includes a `check` subcommand that can be executed to test 
+locally. This subcommand is the same that is executed by the PopperCI 
+service, so the output of its invocation should be, in most cases, the 
+same as the one obtained when PopperCI executes it. This helps in 
+cases where one is testing locally. To execute test locally:
 
 ```bash
 cd my/paper/repo

docs/protocol/getting_started.md

@@ -1,17 +1,154 @@
-# Quickstart
+# Getting Started
 
 _Popper_ is a convention for organizing an academic article's 
-artifacts following a DevOps approach. For an in-depth description on 
-the rationale behind Popper, you can read this article.
+artifacts following a [DevOps](https://en.wikipedia.org/wiki/DevOps) 
+approach, with the goal of making it easy for others (and yourself!) 
+to repeat an experiment.
 
-A [step-by-step guide](./from_scratch.md) describes how to "Popperize" 
-an experiment and manuscript. Additionally, the following is a list of 
+## Quickstart Guide
+
+We first need to install the CLI tool by following [these 
+instructions](https://github.com/systemslab/popper/tree/master/popper#install). 
+Show the available commands:
+
+```bash
+popper help
+```
+
+Show which version you installed:
+
+```bash
+popper version
+```
+
+> **NOTE**: this exercise was written using 0.4.1.
+
+Create a project repository (if you are not familiar with git, look [here](https://www.learnenough.com/git-tutorial)):
+
+```bash
+mkdir mypaper
+cd mypaper
+git init
+echo '# mypaper' > README.md
+git add .
+git commit -m 'first commit'
+```
+
+Initialize the popper repository and add the commit file to git:
+
+```bash
+popper init
+git add .
+git commit -m 'adds .popper.yml file'
+```
+
+### New experiment
+
+Initialize experiment using `init` (scaffolding):
+
+```bash
+popper init myexp
+```
+
+Show what this did:
+
+```bash
+ls -l experiments/myexp
+```
+
+Commit the "empty" experiment:
+
+```bash
+git add experiments/myexp
+git commit -m 'adding myexp scaffold'
+```
+
+### Add existing experiment
+
+List available experiment templates:
+
+```bash
+popper search
+```
+
+Show information about an experiment:
+
+```bash
+popper info blis
+```
+
+Import an available experiment:
+
+```bash
+popper add blis
+```
+
+Commit the new experiment:
+
+```bash
+git add experiments/blis
+git commit -m 'adding blis baseline'
+```
+
+### Popper check
+
+Run popper check:
+
+```bash
+popper check
+```
+
+Show logs for blis experiment:
+
+```bash
+ls -l experiments/blis/popper_logs
+```
+
+### Adding Project to GitHub
+
+Create a repository on github and upload our commits.
+
+### Adding Project to Travis
+
+For this, we need an account at Travis CI. Once we have one, we 
+activate the project so it is continuously validated.
+
+Generate `.travis.yml` file:
+
+```bash
+popper ci travis
+```
+
+And commit the file:
+
+```bash
+git add .travis.yml
+git commit -m 'Adds TravisCI config file'
+```
+
+Trigger an execution by pushing to github:
+
+```bash
+git push
+```
+
+Go to TravisCI website to see your experiments being executed.
+
+
+## Learn More
+
+A more detailed description of Popper is explained in [the next 
+section](intro_to_popper.html).
+
+A [step-by-step guide](../tutorial/from_scratch.html) describes how to 
+"Popperize" a repository. Additionally, the following is a list of 
 examples on how to bootstrap a Popper project (repository) in specific 
 domains:
 
-  * [Data Science](Popper-Data-Science)
-  * [High Performance Computing (HPC)](Popper-HPC)
-  * [Mathematical Sciences](Popper-Math-Science)
+  * [Data Science](../tutorial/data-science.html)
+  * [High Performance Computing (HPC)](../tutorial/hpc.html)
+  * [Mathematical Sciences](../tutorial/math_science.html)
 
-A list of Popperized papers that have been submitted for publication 
-can be found [here](https://falsifiable.us/pubs).
+A list of articles describing the Popper protocol, as well as other 
+Popperized papers that have been submitted for publication can be 
+found [here](https://falsifiable.us/pubs).