Contributing to Documentation

Here's how you can contribute to the Berkeley Research Computing (BRC) draft documentation, thus helping campus researchers make productive use of BRC services:

1. Get a GitHub account

Get your (free) GitHub account.

2. Browse the documentation

Browse the current documentation by clicking links in the list of current Pages at right; that list will look something like this:

3. File Issues for anything that needs changing

You can file Issues for anything that needs changing or adding in the documentation:

• Visit the main BRC Documentation page on GitHub.
• Click the Issues link in the right sidebar:
  
• To create a new Issue, click the New Issue button near top right. Then enter a Title and Comment for your Issue, and click the Submit New Issue button. (See also GitHub's documentation on creating Issues.)
• To comment on an existing Issue, click the Issue's Title. Then leave a Comment at the bottom of the Issue's page and click the Comment button.

4. Edit the wiki pages yourself

If you wish, you can edit or create documentation wiki Pages yourself:

• To edit a Page, navigate to that Page, then click the Edit button near top right. Make your edits, previewing them as you go via the Preview tab at top. When done, you can optionally leave an Edit Message at the bottom, and click the Save Page button. (See also GitHub's documentation on editing wiki Pages.)
• To create a new Page, click the New Page button near top right. Add a Title, enter some content on the Page, optionally leave an Edit Message at the bottom, and click the Save Page button. (See also GitHub's documentation on creating wiki Pages.)
• To learn more about Markdown - the simple codes that you enter to style and format text on your wiki Pages - see Markdown Basics and GitHub-flavored Markdown.

5. Contribute to source code and other materials

You can contribute to the source code and other materials that accompany the BRC documentation. While the specific set of steps for doing this is beyond the scope of the current document, here's a high-level summary.

Stuff you'll need to do once

• Become familiar with the Git version control system. You don't need to be expert at it, but if you haven't used it before, taking at least few hours to explore Git before you dive into working on the BRC documentation can be tremendously rewarding. Two recommendations:
  • Exploring Git via this tutorial authored by Katy Huff: Part I and Part II; and/or
  • Exploring Git through this interactive tutorial provided by GitHub.
• Download and set up a Git client application (command-line or graphical) on your computer.
• Set up authentication. Set things up so that you can connect to your account on GitHub from the Git client application running on your computer. (See the steps beginning with "Next steps: Authenticating with GitHub from Git" in GitHub's documentation on how to Set Up Git.)
• Fork the documentation repository on GitHub. On GitHub, "fork" the BRC documentation repository, creating a copy of that repository in your own GitHub account. (See also GitHub's documentation on how to fork a repository.)
• Clone that repository onto your own computer. Using your Git client application, "clone" the just-forked copy of the BRC documentation repository that's now in your own GitHub account, to create a local copy of that repository on your own computer. (See the steps beginning with "Keep your fork synced" in GitHub's documentation on how to fork a repository.)
• Adding the BRC documentation repository as an "upstream" remote repo. Using your Git client application, add the original BRC documentation repository as a remote repo to your local copy of that repository. This will enable to you bring in changes that others may be making to the documentation.

After doing this, there will now be three relevant copies of the BRC files: the original copy, the copy you've made in your own GitHub account, and the copy you've made on your own computer. You'll work on your own computer, push your changes up to your GitHub account, and from there, submit your proposed changes for consideration.

Stuff you'll need to do each time you want to make changes

• Make changes locally. Make your changes (edits, additions, deletions) to the relevant files in your local copy of the repository, on your own computer.
• Commit your changes. Using your Git client application, commit those changes locally.
• Compare those changes to those made by others and resolve conflicts, if any. Since other people may simultaneously be working on the same documents, it's important to check for any changes they made and resolve any conflicts between your changes and theirs, before pushing your changes up to GitHub. Using your Git client application, "pull" in the original BRC documentation repository (or "fetch" and "merge" that repository into your own), and then use a text editor or other ("diff" and "merge") software that helps you identify differences and decide what to keep, and what to discard, when your changes are in conflict with those of other authors.
• Push your changes up to GitHub. Using your Git client application, push those committed changes, from your local copy of the repository on your own computer, to the forked copy of the repository in your own GitHub account.
• Make a Pull Request. On GitHub, make a Pull Request from the forked copy of the repository in your own GitHub account, to the original BRC documentation repository. By doing so, you're proposing that your changes also be applied to the original repository. (See also GitHub's documentation on making Pull Requests.)