Getting Started

Github is an online service that helps people collaborate on large projects remotely. OpenDoc makes use Github’s platform to manage the documents and provide a simple user interface from which you can make changes to your documents.

Before you proceed with the rest of this tutorial, we recommend that you take some time to complete the following online courses. Each course will take around half an hour to complete, and it will walk you through the user interface of Github, as well as some of the process flows that we’ll be using for OpenDoc.

Introduction to Github (Strongly recommend)

https://lab.github.com/githubtraining/introduction-to-github

Communicating using Markdown (Strongly recommend)

https://lab.github.com/githubtraining/communicating-using-markdown

Reviewing pull requests (Optional)

https://lab.github.com/githubtraining/reviewing-pull-requests

Creating an OpenDoc (IT administrators)

Step 1:

If you do not have a Github account, follow the steps here to get one created.

If you already have an account on Github account, create a new repository and name it in the following convention:

opendoc-<name_of_document> e.g. opendoc-example-doc

Step 2:

Navigate into the working directory and clone the template repo onto your local machine.

cd <directory_path>
git clone git@github.com:opendocsg/opendoc-template.git

Step 3:

Rename the folder to match the name of the repository that was created, and update the remote address for the repo on your local machine. This allows you to make changes to the online repository that was created.

mv opendoc-template opendoc-<name_of_document>
cd opendoc-<name_of_document>
git remote set-url origin git@github.com:opendocsg/opendoc-<name_of_document>.git

Step 4:

Update the following configuration fields in the _config.yml file:

- title                           <------- Update
- repository 	                  <------- Update
- styling_options
	- primary_brand_color     <------- Update
	- logo_path               <------- Update

Definitions:

title: Name of document

repository -> opendocsg/opendoc-

primary_brand_colour: Primary brand color of Ministry/Agency publishing the document

logo_path: Path to logo file in this directory

Step 5:

Copy the markdown documents into the root directory of the repo. The documents have to be in the markdown (.md) format, and you can find out more about getting the documents converted in the following section.

Step 6:

Commit your changes, and update the online repository with the new version.

git add .
git commit -m <"commit_message">
git push origin master

Configuring Github Pages

Follow these instructions on “Enabling Github Pages to publish your site from master or gh-pages”.

Link here

Editing an existing OpenDoc (Content owners)

Follow these steps if you want to make a change to one of your documents. Changes made here will NOT take effect immediately, and you will be able to review the document before publishing it online.

Step 1:

Visit Github.com.

Step 2: (If you do not already have a Github account)

Create a Github account by filling up the required information.

IMPORTANT: Once you have created your account, email us at admin@opendoc.sg with your username and document name and we will grant you permission to edit the document. An email will be sent to you with an invitation to join the document, click on the “Accept Invitation” button to proceed.

Step 3:

Click on the “Sign in” button.

and sign in to your account.

Step 4:

Select the OpenDoc document you want to edit.

Step 5:

Select the “staging” branch.

Step 6:

Select the file that you would like to make changes to.

Step 7:

Click on the “Edit” icon.

Step 8:

Make the necessary edits.

Step 9:

Add a description for the changes made.

Step 10:

Click on the “Commit change” button.

Congrats!!! 🎉🎉🎉 You have made a change to the document.

Updating OpenDoc (IT administrators)

Follow these steps if you want to publish the changes made in the draft environment. This process will require a second person to review the changes before the document can be published live.

IMPORTANT: Before you proceed with the next steps, check if the draft site is reflecting the changes accurately.

For the requestor

Step 1:

Visit Github.com.

Step 2: (If you do not already have a Github account)

Create a Github account by filling up the required information.

IMPORTANT: Once you have created your account, email us at admin@opendoc.sg with your username and document name and we will grant you permission to edit the document. An email will be sent to you with an invitation to join the document, click on the “Accept Invitation” button to proceed.