diff --git a/Gemfile b/Gemfile
new file mode 100644
index 0000000..d611737
--- /dev/null
+++ b/Gemfile
@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+gem 'github-pages', group: :jekyll_plugins
+gem "just-the-docs"
\ No newline at end of file
diff --git a/README.md b/README.md
index 5a6d175..61daa49 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,21 @@
-# github-workshop
+---
+layout: default
+title: README
+nav_exclude: true
+published: false
+---
+
+# GitHub for Collaborative Data Science & Engineering in Industry & Academia
+
+## Steps that we need to deal with:
+
+### Not in the tutorial
0. Everyone should sign up for a GitHub account (before the workshop)
1. 20 or so minutes of basics (Decide about what and who) "We don't make mistakes, just happy little accidents"
+
+### In the tutorial (included)
+
2. Split everyone in groups (tables)
3. Create a repository (one per table). It should have a README, LICENSE, description and gitignore.
4. Add collaborators
@@ -11,7 +25,11 @@
8. Everyone create a branch to address their assigned issue
9. Create a folder and file (come back to give them path instructions)
10. Commit the new file
-11. Do a compare and open a pull request and link to issue in description
+11.1 Do a compare [and open a pull request and link to issue in description]
+
+### In the tutorial (to be included)
+
+11.2 [Do a compare] and open a pull request and link to issue in description
11.b Checkpoint/timecheck (How many tables have a pull request)
12. Assign a reviewer (The person who created the issue)
13. The reviewer changes branches and learns "find/navigate"
diff --git a/_config.yml b/_config.yml
new file mode 100755
index 0000000..df12c92
--- /dev/null
+++ b/_config.yml
@@ -0,0 +1,8 @@
+theme: just-the-docs
+
+title: GitHub Collaborative Workshop
+
+markdown: kramdown
+highlighter: rouge
+permalink: pretty
+
diff --git a/index.md b/index.md
new file mode 100644
index 0000000..6c2e8a3
--- /dev/null
+++ b/index.md
@@ -0,0 +1,61 @@
+---
+layout: default
+title: Home
+nav_order: 1
+permalink: index
+---
+
+# GitHub for Collaborative Data Science & Engineering in Industry & Academia
+
+Welcome to our *collaborative* session on data science and engineering :wave:
+
+This tutorial will walk you through:
+
+* creating a GitHub repository
+* adding contributors to a GitHub repository -- this is a *collaborative* session, after all :grin:
+* creating files, editing and committing changes
+* opening and assigning issues
+* solving issues in a *collaborative* fashion via
+ - branch managements
+ - pull requests
+ - code reviews
+
+The tutorial will deal with the GitHub web interface, therefore there is no need to install anything on your machine, nor to type anything in the command line. We may address these in a more advanced session.
+
+## Prerequisites
+
+1. Your own laptop, with battery charged, a working web browser (Chrome, Firefox, ...), and a good internet connection
+2. A GitHub account. If you don't have one you can sign up here for free: [https://github.com/join](https://github.com/join)
+3. Friends. This is a *collaborative* session, don't forget that!
+ - Please create a team of three/four people
+ - Don't know anyone? There are no strangers here, only friends you haven't yet met.
+
+
+## What are we going to do?
+
+The tutorial is divided in five parts:
+
+1. Setting up
+2. Working all on the same branch
+3. Creating and dealing with issue
+4. Working on your own branch
+5. Merging all together
+
+
+## Ready to start?
+
+Before delving into the tutorial, please remember that **good** collaborations:
+
+* allow a safe space for constructive and honest discussion, therefore
+* do not blame and shame
+* make room and time for teaching and learning
+* accept that there will be mistakes & mishaps (helping each other is a great way to learn)
+
+Indeed, a **good** collaboration
+
+* is first and foremost about working with and respecting other people
+* is NOT a _"soft"_, optional, skill: it is essential!
+
+
+
+
\ No newline at end of file
diff --git a/issues.md b/issues.md
new file mode 100644
index 0000000..470600d
--- /dev/null
+++ b/issues.md
@@ -0,0 +1,58 @@
+---
+layout: default
+title: Creating and dealing with issue
+nav_order: 4
+permalink: /issues
+---
+
+# Creating and dealing with issues
+
+---
+**Learning goals**
+
+* Creating an issue
+* Assigning an issue
+
+---
+
+
+# Step 1. Creating an issue
+
+* Click on the `Issue` tab. This page lists all the issues, which are used to track todos, bugs, feature requests, and whatever you think fit. When you are opening an issue on a public repo, please look for a code of conduct, or for a bug reporting check list and comply with them :relaxed:
+
+
+
+* You are a team, therefore it is good to get to know one another a bit. Therefore, your *feature requests* will be asking (personal?) questions to other team members
+* Think of a question and use it as a title. Be creative, or use one of the questions below
+* How the other team member should address the question? Describe it in the comment. Look at the examples below but please, no poem, the deal is to learn how to collaborate via GitHub, not to win the Pulitzer :stuck_out_tongue:
+
+| Question | Description |
+|:---|:---|
+| What is your favourite food? | Can you list the main ingredients? How often do you eat it? Can you cook it? |
+| Where were you born? | Please, tell me how does it look! |
+| What is your background? | I can see that you joined the AIClub, so you may be keen on AI, data science and the likes, but what did you study? |
+| What do you do? | I can see that you joined the AIClub, so you may be keen on AI, data science and the likes, but what do you do to survive? |
+| Why did you join this workshop? | Please, explain me how proficient (if any) you are with GitHub and what you are expecting from this workshop |
+
+* Submit the new issue
+* Step 1 completed. Your issue has been assigned a tracking number (gotten how the numbering works?)
+
+
+# Step 2. Assigning an issue
+
+* Once everyone has completed step 1, you should be able to see all the questions (hope that there are not too many duplicates!)
+* Select a question you like and assign the issue to yourself. To avoid having everyone dealing with the same question, **quickly** decide who is going to answer what **before** assigning the issue to yourself :sweat_smile:
+* Great, you just committed to answer the question :nerd_face:
+* Write a nice comment explaining that you are dealing with the issue right now. It is nice knowing that an issue has been assigned to someone, but it is even better knowing that someone is actually working on it!
+
+
+
+* Step 2 completed!
+
+
+# Step 3. Checking whether all issues have been assigned
+
+* Once everyone has completed step 2, you should be able to see all the questions and who is dealing with them!
+* Step 3 completed. This was easy, wasn't it?
+
+
diff --git a/own-branch.md b/own-branch.md
new file mode 100644
index 0000000..279c907
--- /dev/null
+++ b/own-branch.md
@@ -0,0 +1,66 @@
+---
+layout: default
+title: Working on your own branch
+nav_order: 4
+permalink: /own-branch
+---
+
+# Working on your own branch
+
+---
+**Learning goals**
+
+* Creating branches
+* Creating files, and committing changes
+* Comparing branches
+
+---
+
+
+## Step 1. Creating a branch
+
+* Note a button `Branch: master`. So far we have used only one branch (`master`) but it is now time to get a branch on our own!
+* Create a branch, using your name as the branch name
+* Congratulation you create your own branch :tada:
+* Note the button `Branch` again: now no longer report `master` but it has your new branch name: you create and checked it out at the same time!
+
+
+
+
+
+
+
+* Step 1 completed. Time of doing some *serious* job here!
+
+## Step 2. Creating and committing a new file
+
+* Remember we created this branch to deal with an issue we self-assigned? Time to address it!
+* Create a new file and use it to answer the question you have self-assigned. Write a few lines (so we can have some material to work on in the next steps) but remember that the goal is not to win the Costa Book Awards :stuck_out_tongue:
+
+
+
+
+
+
+
+
+
+* Commit with a message/description as done before. Are you in the correct branch, the one with your name?
+* Step 2 completed. Will your literary efforts be enough?
+
+## Step 3. Comparing branches
+
+* After step 2, your branch will be one commit ahead of `master`. Can you see it?
+* Let's now compare your branch with `master`. Any difference?
+
+
+
+
+
+
+
+
+* Does everything look good? Everything there?
+* Step 3 completed. Time to move on and push these changes to the original repo.
+
+
diff --git a/pull-request.md b/pull-request.md
new file mode 100644
index 0000000..e69de29
diff --git a/same-branch.md b/same-branch.md
new file mode 100644
index 0000000..00bd1bb
--- /dev/null
+++ b/same-branch.md
@@ -0,0 +1,40 @@
+---
+layout: default
+title: Working all on the same branch
+nav_order: 3
+permalink: /same-branch
+---
+
+
+# Working all on the same branch
+
+---
+**Learning goals**
+
+* Editing files and committing changes
+* Understanding basic issues underlining collaborations
+
+---
+
+
+## Step 1: Editing a file and committing changes
+
+* The work carried on on our repo will be a collaborative one, therefore all the members of the team need to be acknowledged. On the main repo's page, you can see the content of the README file, which now just reports the repo's name and description. What better place to list all the contributors?
+* Press the pencil on the left of the `README.md` box
+* In a new line, immediately below the repo's description, add your name
+* Include a commit message (you can use the suggested *Update README.md* or be more precise) and an optional extended description (what did you do?). Detailed commits are always highly appreciated, as the person that made them :wink:
+* We will commit directly to the master branch (no action needed, but note the option of creating another branch)
+* Commit changes
+* Step 1 completed. Not too hard, right?
+
+## Step 2: Observing the results
+
+* Wait for everyone to have completed step 1
+* Refresh the main repo page
+* Is your name still immediately below the repo's description?
+* What has happened? What can possibly go wrong in a real world scenario? Discuss with your team members :loudspeaker:
+* Also, how many commits there are now?
+* Step 2 completed. Let's move to a more organised (and less dangerous) way to collaborate
+
+
+
diff --git a/setting-up.md b/setting-up.md
new file mode 100644
index 0000000..3ab969d
--- /dev/null
+++ b/setting-up.md
@@ -0,0 +1,71 @@
+---
+layout: default
+title: Setting Up
+nav_order: 2
+permalink: /setting-up
+---
+
+# Setting up
+
+---
+**Learning goals**
+
+* Initialise a GitHub repository
+* Adding contributors, and accepting invitation to contribute
+
+---
+
+
+
+## Step 1: Initialising a repository
+
+* You will collaborate on a single repository, therefore you will need to create **one and only** one: choose one person in your team to do so (but watch out what they are doing)
+* The *chosen one* should now go to their GitHub page (`https://github.com/loginname`) and click on the `Repository` tab. This page lists all your repository -- it may already include some :nerd_face:
+* Create a new repo(sitory)
+
+
+
+
+
+
+
+* Your repository will need a name: agree on one! If you are having a creative block, names like *"github-collaborative-workshop"*, or *"AIClub-githib-workshop"* will be amazing, trust us :sweat_smile:
+* Your repository will also need a description: why not *"A collaborative repo"*?
+* Your repository can be *public* (everyone can access it) or *private* (only you and your collaborators will be able to access it). Since early 2019, GitHub allows an unlimited number of private repositories, but don't be shy -- and think of all the good you get from open access code. Time to give some love back?
+* GitHub allows initialising a repository with a README file. Please, do so
+* GitHub allows generating a `.gitignore` (which lists all the files that should not be included on a repo) and a `licence` file. Let's ignore the former but let's include the latter (quite a list, isn't it?)
+* Choose an MIT license to keep it simple. Licenses are very important so next time you create a repo take your time to read the options and choose the one that fit your project best.
+
+
+
+
+
+
+
+* Create the repository!
+* Step 1 completed. Give each other a high five :raised_hands:
+
+## Step 2: Adding contributors
+
+* You landed on your repo main page. Only one person is allowed to _"collaborate"_ to it: the repo's owner. Time to change this :two_women_holding_hands: :couple: :two_men_holding_hands:
+* The repo's owner should now click on the `Setting` tab
+* Look then for adding `Collaborators` (you may be asked to type your password)
+* Add the other members of the team, one by one, using their GitHub username or email
+
+
+
+
+
+
+
+* Step 2 completed. Time for everyone to roll up their sleeves :muscle:
+
+
+## Step 3: Accepting an invitation to contribute
+
+* All the member of the team should receive an email inviting them to collaborate. Please accept: the more, the merrier!
+* Step 3 completed. Ready for the real work? From now on, everyone has do to their homework, so no more looking at the *chosen one*!
+
+
+
+