Previewing and editing the handbook on your local computer is the easiest way to make changes, while knowing that they will look like you intend when you submit the merge request.

Where to get help

Everyone in the dev team is highly familiar with how to use Git, Editor and Merge Requests so you can ask anyone of them for help.

Prerequisites

  1. Clone the repository from https://gitlab.com/timezynk/handbook
  2. The handbook is built using hugo. Install it by following the steps in Installing Hugo

Making changes

  1. Open the folder in your favorite editor, for example https://code.visualstudio.com/
  2. Start hugo by running hugo server
  3. Make some changes! The format is Markdown and you can read more about the syntax at https://commonmark.org/help/
  4. You can now view your changes live at http://localhost:1313/handbook/

Commit changes

  1. Open a new branch for your edits git checkout -b <branchname>. The branchname needs to be a single word, possible separated with hyphens, for example improve-sales-process or update-values.
  2. Check for new files and add them if necessary git status
  3. Commit your changes git commit -am "Proposal for improved sales process"
  4. Push the branch git push
  5. The message from the push will give you a link you can use to create a merge request. Otherwise create one manually

Create awareness

Ping the #general slack channel or the CEO directly to have your changes reviewed and accepted.

Editing handbook in browser

Create new page

  1. Go to https://gitlab.com/timezynk/handbook
  2. Click button “Web IDE”
  3. Go to folder “content” -> “page” -> Choose the folder for the department that best suits your new entry
  4. Add new file (+) to chosen folder. Name the file with lower letters and _ instead of space. Add .md to ending (my_new_file.md), do not choose a template.
  5. Add message about what file you added and commit

Edit your page.

  1. Check (and steal) styling from other pages or this tutorial, do your stuff.
  2. Take a look at the tab “Preview Markdown” to see that everything looks good.

Add page to Index

  1. Go to /content/_index.md/
  2. Add name and link to your new page under the department you created your file in.

Commit changes

  1. Make sure you’ve made all changes you want to before you commit. Avoid making several commits in a row.
  2. Press “Create commit…” and add a message of the chances you’ve made, then commit changes to new branch.
  3. Ping the #general slack channel or the CEO directly to have your changes reviewed and accepted.