Here’s the recording of our second Documentation Office Hours from 8th March 2024:
The one where we attempt a live GitHub demo
00:05 - Introduction and updates
05:40 - Live git and GitHub demonstration
06:23 - GitHub task list
07:57 - Forking the Open Documentation Academy repository
09:14 - git clone to create a local copy of your fork
11:03 - git checkout to create a new local branch to work in
13:22 - Create and edit any proposed documentation changes
14:36 - git add and git commit to stage which files you want to change
15:01 - git push to push local changes to your GitHub fork
15:50 - Create a pull request to ask that your changes are considered
19:24 - Responding to review comments
21:00 - Merge the pull request
We split the hour into two sections with the first section covering news and updates followed by a live GitHub demonstration (re-recorded for this post because the original was 10 minutes longer and a bit messy). The second section was a chance for attendees to ask questions and was not recorded.
Questions
Q: Is using GitHub and git the only way to contribute?
A: No. We chose GitHub primarily because it’s accessible to everyone, offers a good interface to issue and task tracking, plus a strong collaborative comment and review system. There’s also an excellent web-based text editor that most people can use without using git directly.
But we also wanted to help people gain git experience in a safe and non-judgemental environment, because it’s so commonly used in open source and documentation projects. But this isn’t at all a strict requirement, and we’re happy to create tasks that don’t involve any git use at all, or use other methods of documentation collaboration.
We’re also working on our own GitHub process documentation to help make using git as accessible as possible. We’ll share this as part of the Academy, and also use this as the basis to create a few tasks related to its relevance and maintenance.
Q: Do all contributions need to be made to the Open Documentation Academy repository?
A: This is no, too. We’re centralising on a single repository only for convenience. It’s easier to share a single location and for us all to work from the same place. We also want an open location where people can always access, share and link to their contributions, as well as a place where we can publicly acknowledge the contributions being made. But this doesn’t mean you have to merge your work into the Open Documentation Academy repository. A task may specify a different location and a different process. These requests are common to working with documentation, and we want to remain as dynamic and flexible as possible, while also being predictable and consistent.