Editing the Handbook

This handbook is our single source of truth and needs to be preserved that way. It is essential that whenever someone visits the handbook, they are met with up-to-date and correct content. This is why we chose to develop it inside a repository and treat it like a piece of software. Like a lot of other companies, we have tried to document everything we do in a lot of different ways, including Confluence, Notion, Google Drive and more… However, they all shared the same problems;

• They grow stale. Content gets outdated and organization gets increasingly more complicated
• Changes made to the documentation weren’t reviewed properly and would instantly be applied
• It’s extremely hard to track changes and collaborating on changes is messy

For these reasons, this handbook is built with a static site generator (HUGO) and managed through a version-controlled Git repository. For our coders and more technical colleagues, this is a dream come true—but for our less technical colleagues, this may initially sound scary and presents a bit of a learning curve. But don’t worry! We’ll guide you through the process and you’ll learn to love it.

For anyone unfamiliar with Git, the Git Documentation book is a great resource to learn more. Some of this may be necessary for you to learn before editing the handbook, but definitely not all of it.

1. We can track all changes made to our handbook
2. Anyone at the company can propose edits to the handbook, but they always need to be approved by another team member
3. Edits are always proposed with a merge request, which makes it very easy to review the changes made

In order to learn how to edit the handbook, it’s essential you understand a few technical components of how the handbook is built.

• Our handbook is built on Hugo, a static site generator that translates regular Markdown files into HTML files.
• The main branch in our repository is the “live” version of the website. Whenever a new commit is made to this branch, a pipeline to rebuilt and update the website is automatically triggered.
  • This pipeline is currently managed through Netlify, which directly reads from our repository.

Now, this poses a problem, as you won’t be able to see how your changes look like live, until the commit has been approved and merged into the main branch. Thankfully, we’ve developed a way for you to view all of your changes on your local computer, and only commit the changes when you’re satisfied and have seen it live.

1. A (process) problem comes up, frequently in an issue, on Slack or through a StackOverflow question.
2. A documentation change or addition is proposed through a Pull Request on the handbook GitHub page.
3. Once merged, the change is announced by linking to the diff in the MR or commit. The new page is automatically linked to in the #handbook Slack channel, notifying the entire team of the change.

Sometimes you want to have real time editing of a process or handbook page during a meeting and you need to use a Google Doc for that. When doing so, the first item should be the URL of the handbook page this content will be moved to when the meeting is over.

Checkout the video below where Stefan explains everything.

Very often you’ll be reading through handbook pages online, and you may notice an error. It could be a typo, or a piece of information is outdated or no longer relevant. In this case, you just want to quickly be able to change it. We’ve made sure to include a way to easily do that by adding the Edit this page button at the top of each individual handbook page.

This button will take you to our GitHub Repository and let’s you edit the Markdown page directly. After you’ve made the changes, scroll down and commit your changes. Make sure however, to always create a new branch for the commit and to start a pull request. This way, we’ll always have somebody to approve your change.

• Make sure your branch name is informative
• Make sure your commit message is informative

If the changes you want to make to the handbook are too large to do it online (e.g. a completely new page), you’ll need to resort to making edits locally.

The easiest and best way to start editing the handbook locally and viewing your changes live in your browser is by cloning the repository and opening it in an R Project. This may sound daunting, but it’s actually super simple, just follow the steps below.

Step 1

Installing R & Rstudio

The first step is to download R & RStudio and install both of them. Since you work at Gradient, you’ll likely already know how to, but if not, following the link below will guide you through the setup.

A Guide to Download & Install R & RStudio

Step 2

Cloning the Git Repository

Once you have R and RStudio installed, you should be able to launch RStudio. At this point, RStudio provides a very easy way to “clone” a local Git repository. Basically this means that you’ll get your personal, local version of the handbook. Any changes you make on your computer, will not be seen on the live version until you push the changes through a merge request.

See below for a step by step guide to clone the repository through RStudio

1. Open RStudio and go to Tools > Global Options… click on Git/SVN
2. Check Enable version control interface for RStudio projects
3. Set the path to the Git executable that you just installed. Open a shell, if you don’t know where Git is installed. Windows: type where git and hit enter. The path should be something like: C:/Program Files (x86)/Git/bin/git.exe Linux/OS X: type which git and hit enter. The path should be something like: /usr/bin/git
4. Restart RStudio, if it worked out you will find the Git icon on the top toolbar, as shown below.

5. setup Git: Configure Git and set your user name and email (the email address you used to register on GitHub). You can directly open the Git prompt from within RStudio. User name and email needs to be set only once. Go to Tools > Shell to open the Git Shell to tell Git your username and GitHub email.

git config --global user.name 'yourGitHubUsername'
git config --global user.email 'name@provider.com'

6. create a new RStudio project with Git version control: Now everything is ready to create a new project with Git version control in RStudio. In RStudio Select File > New Project.., select Version Control, Choose Git, then provide the repository HTTPS link, select the R workspace folder and create the project. RStudio now copies (clone in Git terms) the content of the repository to your project folder. The content of the GitHub repository should now appear in the Files pane of RStudio and you should see there the created README.md.

Step 3

Installing Blogdown & Hugo

Since we use R & RMarkdown so much, it was only logical to base our handbook (although it doesn’t depend on either!) on blogdown. Blogdown is a way to create websites with RMarkdown documents.

Open up an R Script, or just write the following in your console in RStudio:

install.packages('blogdown') 
library(blogdown)
blogdown::install_hugo() 

This should install both Blogdown and the correct version of Hugo. To be sure, let’s check it with:

blogdown::check_hugo()

If some of the above isn’t working properly, try to restart R or RStudio (or both) and try again.

Step 4

Serve the site locally

Now that you have R, RStudio, Blogdown and Hugo installed, we’re all set! If you haven’t done it after installing Blogdown, please restart your RStudio. You should now be able to see Serve Site from the Addin panel at the top bar. Press this and your viewer will show you the full handbook website! In the viewer tab, press the third button (show in new window) to open it in your browser.

That’s it! You’re ready to start editing and seeing your changes locally. Any time you save a file in the handbook directory, the website will get updated automatically, it’s also super quick, so you can see your changes in action in real-time!

The structure of the Handbook is extremely easy, and works just like your folder structure would. The repository only contains a few folders that you’ll need to interact with. All other folders are better left untouched unless you know what you’re doing.

The main folder that contains all of the documentation in the handbook is called content. This is your starting point. Creating a new folder inside the content folder will start a new directory tree. However, this will only work if you include a file called _index.md inside this folder. See the content/handbook directory as example below:

This _index.md has only a few lines to indicate the title and the weight (which determines the order the page is shown in the navigation menu). Without this file, the directory won’t show up on your site!

---
title: Handbook
weight: -20
---

You also saw a few other pages in the folder, and they start with the same description, but you can actually add content beneath the --- line. You can also see another folder in there called handbook-style-guide. This folder goes further in the navigation tree and has more pages contained. This process can be repeated endlessly.

The one difference between the handbook-style-guide folder and the handbook folder is a single line in the _index.md file;

---
title: Handbook Style Guide
weight: 30
geekdocCollapseSection: true <----
---

This parameter allows you to create a collapsible folder (as you can see in the navigation menu). This is useful in subpages that you don’t need to show immediately, but only when a user drills down for it.

The full file system structure for the Handbook specific drilldown is as follows:

content/
├── handbook
│   ├── _index.md
│   ├── handbook-usage.md
│   ├── handbook-editing.md
│   └── handbook-style-guide
│       |── _index.md
│       ├── introduction.md
│       ├── high-quality-writing.md
│       ├── using-markdown.md
│       └── using-shortcodes.md

The /post folder inside the content folder is for announcements, news or other temporary articles. Posts in here can also be created through .Rmd files, but more on that later.

So, now that you know where, inside the full file structure, you need to place your new article, we’ll detail how to create a page. As mentioned below - you’ll need to create a .md file. This is a standard markdown file that you may have seen in other places. Many web portals use the same format, so it’s been tried and tested. This markdown file needs two parameters at the top of the page to work before you start editing:

---
title: Title Of Your Page
weight: 30
---

• The title is self explanatory. This is the name at the top of your page and the name in the navigational menu.
• The weight parameter is a little different. This parameters allows you to organize your pages in the file structure.

E.g. in the example above, the following weights are added:

content/
├── handbook
│   ├── _index.md
│   ├── handbook-usage.md             <- weight: 10
│   ├── handbook-editing.md           <- weight: 20
│   └── handbook-style-guide          <- weight: 30
│       |── _index.md                 # Weight restarts
│       ├── introduction.md           <- weight: 10
│       ├── high-quality-writing.md   <- weight: 20
│       ├── using-markdown.md         <- weight: 30
│       └── using-shortcodes.md       <- weight: 40

The reason we use 10-folds is really only because we may want to insert new pages between 10 and 20. This can easily be done by adding weight:15. This way you don’t have to change the weights of the other pages constantly.

Now that you have the correct information at the top of your file, you are ready to get started! For more information on how markdown works, please refer to the Handbook Style Guide and the pages inside.

Last but not least. You’ve finally written up your new article. You’ve placed it in the right folder, with the right weight, and you’re happy with how it looks on your locally rendered handbook website. You’re ready to share it with the rest of the team!

So let’s go ahead and do just that. First—make sure that you are working in a different branch than main. Nobody is allowed to directly commit changes into the main directory, it’s only possible to get new commits on the live pages through a Pull Request. In RStudio it’s as simple as going to the Git tab and pressing the New Branch button. In this new branch, you can do whatever you want to the handbook, and you can commit and push your changes. (If you don’t know what this means, please head over to the Why A Git Repository) section.

Once your satisfied with the changes in your branch, you can create a Pull Request (PR) and assign a reviewer to look at the proposed changes. Right now, you can assign Stefan Musch to all of the PR’s, but eventually, each handbook section will have it’s own maintainer.

1. Visit https://github.com/g6t/handbook/pulls
2. Click New pull request
3. Set the to be compared branch to the one you want to merge

4. Click Create pull request
5. Assign a Reviewer
6. Apply a label (e.g. documentation, enhancement)
7. Provide a detailed overview of the pull request and why it should be merged into the main handbook.
8. Click Create pull request
9. Wait for the reviewer to either merge the branch if it’s approved, or make any changes requested by the reviewer.
10. Profit!