Editing the Documentation#

The source code is currently hosted on Dr. McCurry’s Personal Forgejo Server. You will need an account, so please check your email for your password if you haven’t already set up and changed your password. The source code is tracked using git, a type of version control system, that notes every change ever made to a file. It attributes changes to specific users (or emails) so that you always know where a change came from and when it was introduced. The true power here is that changes can easily be merged or removed if needed without causing odd conflicts as multiple people edit a document individually. If you’re interested, you can read more on git online, but it is not necessary for CHEM442.

Note

You do not need to install any additional software to edit the documentation, but you are welcome to try it out if interested!

A popular host for git repositories is GitHub, but it is owned by Microsoft and has recently forced a lot of AI on users, so Dr. McCurry has chosen to host his own using Forgejo. Forgejo shares a lot of similarities with GitHub, so if you ever do work on GitHub (or alternative sites like Codeberg), you’ll feel right at home.

Anyway, let’s cover how to edit the documentation. There will be some new terms that we’ll come across, but you probably don’t need to know the intricate details of git unless you are interested!

Forking the documentation repository#

Tip

This will work best on a full computer, rather than a phone. These directions have been written assuming that you’re at a keyboard.

  1. After logging in to Forgejo, you will be presented with a list of recent changes to some repositories (or projects) that you follow. Dr. McCurry has added the CHEM442 class to the CHEM442 team, so you should already be following the CHEM442/InstrumentDocs and CHEM442/442LabManual repositories. For the instrument documentation, we want CHEM442/InstrumentDocs, so click on that repository under the Repositories tab on the right side of your screen.

  2. You will be presented with the “source code” of the documentation. The documentation is built from a series of files that are all written in plain text. These have simple formatting and it should be easy to pick up. Don’t worry — you don’t actually need to code anything! The content you’re seeing is owned by Dr. McCurry, so you won’t actually be able to edit it directly. Instead we’re going to “fork” (create a copy) of this code to your own repository. Click the “Fork” button at the top right of the screen.

  3. You will be presented with a “New repository fork” screen. The default options should be OK to use, so just click the “Fork repository” button at the bottom of the screen.

  4. You will be brought to your repository. Note that the top of the page now says username/InstrumentDocs instead of CHEM442/InstrumentDocs.

Editing a file and committing changes#

All edits will be made in your forked repository, rather than the CHEM442/InstrumentDocs repository. Whenever you log in to Forgejo in the future, head to your version for edits!

Important

Sometimes Dr. McCurry’s source code will get ahead of yours due to inclusion of edits from other students. If you ever see a message at the top of your repostiory that says something like

This branch is 1 commit behind CHEM442/InstrumentDocs:main

hit the “Sync” button to bring in the changes before you do your edits!

I’m assuming we’ll edit an instrument, so let’s take a look at one!

  1. Click the instruments folder in your repository.

  2. You will be presented with a list of instruments that we have on campus. Click the folder for the instrument you would like to work on.

  3. All instruments have a index.rst file. This is the general overview of the instrument. If you would like to edit the procedure, I would encourage you to make edits in a procedure.rst file if it exists. I’m hoping the file names are explanatory enough. When in doubt, use index.rst and I’ll move it around as needed. Click on the file you would like to edit.

  4. Here, you’ll see the raw file! Near the top of the file, there should be a pencil icon that you can click to start editing.

  5. The file is written using the ReStructured Text format. There is a fantastic primer online that lists a lot of the possibly useful formatting features. Feel free to use any, but generally, you will just type if you need paragraphs, or put a 1. or 2. in front if you want a numbered list. The numbers don’t actually need to be in order, the document generator will fix that! Note that headings are just lines of text that are “underlined” with either hyphens (-), equal signs (=), or some other character. Switching between different characters moves from heading to subheading to subsubheading, etc. Type in your edits to the file.

  6. Once done, scroll to the bottom of the page. Here’s where you’ll save (or commit) your changes. Generally, it’s a good idea to be descriptive about what you did, but when in doubt, you can use the default (e.g., “Update instrument/index.rst”). Keep the “Commit directly to the main branch checked” and hit “Commit changes” when you’re done.

Note that these changes have only been made to your repository. In order to merge them to the class we need to start a “Pull request”!

New files and images#

Note

I will not require you to upload or insert images, but I do encourage you to take screenshots as this helps future users follow steps a bit more clearly.

If you would like to include images that you have taken, please send me an email with the desired images named with placeholders that you include in your documentation edits. For example, send me a file named scan1.png and inside your documentation, include the phrase scan1.png goes here.

While it would be great if you could upload your images directly to Forgejo, I have to pay for storage and would appreciate the ability to edit or scale down your images into a more manageable size!

For new text files, feel free to use the “Add file” button at the top of your repository and commit changes as described above.

Creating a pull request#

You can create multiple commits (changes) prior to creating a pull request. Make sure not to hold off on creating a pull request too long, though, or your edits won’t match the new documentation!

  1. Click the “Pull requests” tab near the top of your repository (under your repository name).

  2. Click “New pull request”.

  3. Notice the direction of the arrow that’s shown. We want to pull your changes into Dr. McCurry’s repository. Change the left dropdown to CHEM442:main. The right dropdown should stay at “pull from:username:main”.

  4. Review the changes. You should note a “-” next to lines that have been removed and a “+” next to lines that have been added. Click the “New pull request” button if the changes look good.

  5. A default commit message should be provided for you. You can add in any other comments or details that you want me (and the class) to see. Once finished, click “Create pull request”.

  6. Now, you just wait for me to review your request and hopefully I’ll pull it in to the official documentation!

On this page
Show Source