zhuyunlong / write-the-docs-tutorial

GitHub Pages and documentation tutorial

Tutorial: Learn GitHub by building a website

This repository contains the files used with Mapzen's GitHub tutorial at https://mapzen.com/documentation/guides/github-tutorial/.

GitHub for Documentation

This tutorial was originally presented at the GitHub for Documentation workshop from Write the Docs - San Francisco on October 27, 2016. The tutorial was later adapted into Mapzen's documentation set.

Original workshop information

Presenter: Rhonda Glennon, @rmglennon

GitHub enables people to collaborate on projects, and many organizations use it for managing both software code and documentation. At this Write the Docs, you will get started with GitHub by applying its tools to building a documentation website.

In this hands-on workshop, you will:

• Get an introduction to the Git version control system, terminology, and the GitHub workflow.
• Create a simple website with GitHub Pages and use GitHub for documentation.
• Learn how you can support open-source projects by contributing documentation.

The session is designed for beginners to GitHub, but all levels are invited.

Bring your laptop so you can follow along with the presentation. Any operating system will work, and you need only a browser. If you are new to GitHub, create a free, personal account at https://github.com/join before arriving to save time.

Resources from the presentation

Examples of github.io websites

• https://square.github.io/
• https://microsoft.github.io/
• https://disney.github.io/

Markdown syntax reference

• https://daringfireball.net/projects/markdown/

Training classes from GitHub

• https://services.github.com/training/
• Includes free self-paced classes and webinars

GitHub branching and flow diagrams

• Octopus Git branch: http://imgur.com/gallery/YG8In8X/new
• GitHub Flow: https://guides.github.com/introduction/flow/

Examples of documentation repositories

• CircleCI has a repository with only documentation-related files: https://github.com/circleci/circleci-docs
• Kubernetes repository contains both code and documentation files: https://github.com/kubernetes/kubernetes
• Example pull request about documentation with team discussion: pelias/documentation#163

Make four pull requests by October 31, 2016 and get a free Hacktoberfest t-shirt: https://hacktoberfest.digitalocean.com/