To live our values of open collaboration and our intention to Open Source as much of our organisational model and systems, Enspiral has decided to use GitHub as the primary place to host our org documentation.
A core goal with this decision is to make it easy and accessible for many people to contribute to documentation at Enspiral. Most people see GitHub as a place for coders and techies so we've made this guide and videos to demystify the platform - a help guide for using GitHub for documentation rather than code.
- What is GitHub and why use it for documentation?
- GitHub terminology
- Signing up and visiting the Repo
- Contributing to documentation by making a Pull Request
- Discussing the Repo by posting Issues
- Master Markdown
- Practice now!
Click to view video
-
Repository (Repo) - Essentially a projects folder. A repository contains all of the project files (including documentation), and stores each file's revision history.
-
Master - the master copy version of a repository. This is the official 'source or truth'.
-
Fork - when you are a contributor to a repo and click to edit the file it will make a personal copy of the master for you that sits under your GitHub account. Forks allow you to freely make changes to a project without affecting the master. Forks remain attached to the master, allowing you to submit a pull request to the master's author to update with your changes.
-
Pull Request - proposed changes to a repository submitted by a user and accepted or rejected by a repository's collaborators. Like issues, pull requests each have their own discussion forum.
-
Issue - suggested improvements, tasks or questions related to a repository. Issues can be created by anyone for public repositories, and are moderated by repository collaborators. Each issue has its own discussion forum where people can comment to solve the problem the issue identifies.
-
Collaborator - a person with read and write access to a repository who has been invited to contribute by the repository owner. They can make edits to the Master branch without needing to submit a pull request and approve pull requests contributors have submitted.
-
Contributor - someone who has contributed to a project by having a pull request merged by a repo collaborator but does not have collaborator access.
-
Organisations - a group of two or more users that typically mirror real-world organizations. They are administered by users and can contain both repositories and teams.
For a full glossary of GitHub terminonology see https://help.github.com/articles/github-glossary/
Click to view video
Click to view video
Click to view video
Markdown is the simple formatting language used on GitHub to add rich features to your documents. To use Markdown in your documentation, add .md to your file name.
Click to view video