Quickstart guide

Joe Corneli edited this page Feb 16, 2016 · 66 revisions

Prelude

The micro quickstart guide on peeragogy.org suggests the following steps:

  1. Create a Github Account https://help.github.com/articles/signing-up-for-a-new-github-account/
  2. (optional) Contact us in real time via our public rooms in Gitter https://gitter.im/Peeragogy
  3. (optional) Create a https://hypothes.is/ account if you want to make comments.
  4. (optional) Connect with +Peeragogy Project on Google+ and join our weekly meetings.
  5. Start editing, discussing, and commenting.

We will expand on this below.

Before that, let's just mention what you're looking at right now. This is a wiki page associated with one of the Peeragogy Project's repositories on Github. In particular, this repository contains the source code for the print edition of the Peeragogy Handbook. The Peeragogy Handbook is

The no longer missing (free/open source) guide to peer production and peer learning

There are lots of other things to discover here and we give you a quick guided tour, next.

Introduction

We aim to welcome all contributions to the Peeragogy project with unconditional love.

We've started to illustrate what we mean by that in this mindmap, and we hope the image is a useful first step toward making our project easier to understand, access, and work with.

Unconditional Love [source] To view a large version of this, right click and "View Image".

You'll probably have some questions in mind at this point. Great!

Nontechnical: Getting to know us.

The easiest way to get started would be to join one of our weekly hangouts. Send your expression of interest to +Peeragogy Project or peeragogy @ gmail . com to get an invite to one of these.

For a quick overview of the project's current priorities, please read the Distributed Roadmap page in the Peeragogy Handbook. Feel free to have a browse through the book -- you certainly don't need to read the whole handbook before taking your next steps with peeragogy. But, if you find a part you think you can improve, that's awesome. You can download the book for free, or read it, on peeragogy.org.

Recent comments from across the site are collected in this Digg folder (requires login).

You can generally contact one of us live or almost-live via our public rooms on the Gitter chat service https://gitter.im/Peeragogy (requires a Github login).

To review recent work on the project, please visit http://is.gd/peeragogy_wrap.

Semi-technical: Making an edit.

First, join Github if you have not done so already. Have a look at https://github.com/Peeragogy/Peeragogy.github.io which is the backend of peeragogy.org.

If you're already a member of the Peeragogy organization on Github...

... Then you have edit access and you can change pages in that repository directly. In fact, you can use Github like a wiki, and to begin, that's the simplest thing to do. For example, to edit the license page -- to make sure you've signed the license, or to link your name to your home page, for example -- browse to license.md in the main directory and click on the "pencil" icon. You'll get a straightforward editing interface. Add a summary of your change in the box at the bottom of the page, and go ahead and commit to master. Once it's saved, your change will show up on http://peeragogy.github.io/license.html. Hopefully you'll agree that it really couldn't be simpler. Other source files for the book are also saved in the main directory of Peeragogy.github.io in markdown format, and now that you know how, feel free to dive in and edit any page you like. A history of changes appears here.

If you're not a member of the Peeragogy organization....

.. then you can still contribute, but it will require a couple extra steps. Fork the page via the "Fork" button in the upper right on https://github.com/Peeragogy/Peeragogy.github.io and then make changes in your own version, then send pull requests and they can be merged. You can also do all of this online through the Github interface if you want! Browse to the file you would like to edit in your fork, for example: https://github.com/USERNAME/Peeragogy.github.io/blob/master/a_specific_project.md. Click the "pencil icon" in the grey bar near the top of the screen, and carry out your edits. Once you've made the change you'll have to submit a pull request. Note: for us to include changes, you'll have to agree to our license in writing.

Making new pages

If you create a new page, make sure to add the title metadata at the top of the file, so that Jekyll/Github Pages will know that the file is there. For example, here's how the top of the Social Bookmarking article is formatted:

---
title: Social Bookmarking
---

Social Bookmarking 
==================

*Author/Editor*: Howard Rheingold April 2 10:41 AM Pacific;
editor Gigi Johnson, April 10, 1:59pm PDT

The title: ... tag that's necessary for conversion to HTML to work.

Technical: Editing via commandline.

If you like, you can also use the power of Git to edit the book comfortably in your favorite text editor. This can be faster and you can make more wide-sweeping changes.

git clone https://github.com/Peeragogy/Peeragogy.github.io
[or your fork, if you're working in a fork]
[edit .md files]
git commit -a -m "describe changes"
git push
[some time later]
git pull
[edit .md files]
git commit -a -m "describe new changes"
git push
[repeat]
[If working in a fork, send pull requests from time to time.]

Previewing changes

If you want to preview changes you before you post them, in other words, see how they will look on the site before you run git push and/or send a pull request, then you can install Jekyll and build the site locally on your own machine. Alternatively, you can view your fork of the site using Github Pages, but you'll need to make one change before the Github Pages will work on a fork. The reason it works like this is explained, more or less, on Github's User, Organization, and Project pages documentation.

Previewing your fork over the web

Here are the glorious details:

git checkout gh-pages 
git rebase master 
[now make some changes]
git push origin gh-pages
[see how they look at http://USERNAME.github.io/Peeragogy.github.io]
git checkout master 
git merge gh-pages
git push origin master
[now submit a pull request]

(More info: Easily keep gh-pages in sync with master, Merging vs Rebasing.)

Previewing locally

To preview changes using Jekyll on your own computer, you can skip the above, but you will need to do some other setup steps instead:

gem install github-pages
gem install bundler
gem install execjs
gem install therubyracer

And then, from the top-level directory, when you want to preview, run:

bundle exec jekyll serve

Browse to http://0.0.0.0:4000/. Read the Jekyll docs for more information.

So you really want to geek out?

This section of the Quickstart guide is for people who want to help with technical editing for the production of the print version of the book, or who want to write some CSS or other code to improve the look and feel of peeragogy.org -- or who want to dive into other more technical topics. If that doesn't describe your interest, no worries.

If it does, please help us finish this manual :-)

  • Technical editing to produce the PDF version of the book with LaTeX: start here
  • Website stuff: learn more about Jekyll and contribute via the Peeragogy.github.io repository, or send pull requests from your fork
  • Learn more about Git and help manage our repos and releases
  • Legal stuff: organizations, rights, lawsuits, subpoenas, and other exciting stuff as needed!
  • Other technical and non-technical stuff: talk to us during a hangout, or join the peeragogy google group, or hop on Gitter and discuss more with us there.