Create an Assist Tutorial Post From Google Docs to the Assist Repository

July 14, 2017 by Nia Ordinario

A brief overview and workflow for creating an Assist tutorial post in Google Docs and Jekyll.

screenshot of assist website

Introduction

Assist is a support documentation site built with Jekyll, a simple, blog-aware, static website generator. Here is a general overview and workflow for creating an Assist post from drafting in Google Docs to post in Assist. If you plan to contribute to Assist, the following will give you an overview of what you will you need to know to successfully contribute a high quality post.

Overview

A newly created Assist post will go through a process of 3 stages, where each stage has a location where the new post lives. Below is a graphical illustration of the stages.

stages of assist post writing

Jekyll and Markdown

word jekyll and test tube

Before we cover the process, let’s take a quick look at the technical side of things. Jekyll is simpler than a content management system like WordPress, in that you can write and publish posts by managing a folder of text files on your local computer. These files are synched to a COE Github code repository that Assist mirrors at assist.coe.hawaii.edu (think of it like ‘hosting’). These files are written in Markdown, which is a faster and more efficient way to add formatting to text, sort of like HTML markup. When these Markdown files have appropriate metadata (also called Front Matter), Jekyll recognizes that they are posts, and adds them to the site.

Anyone can make edits to individual pages or parts of the site by submitting a pull request on Github, but to add a new post or make significant edits, it’s better to install Jekyll on your local computer to verify changes there first. More on this further down in this post.

Draft

The first stage in the process is to write a draft of the tutorial in Google Docs. A template is provided to take out the guesswork on the Front Matter section, since the post will need to be in Markdown. Once the draft is written, you will need to store the draft in the drafts folder.

screenshot of google docs word draft

Once you write a tutorial draft, send your draft to Billy or Frank for review. The review process is necessary to provide our users accurate, informative, high quality posts. Once approved, you can transfer your tutorial draft into Jekyll!

 Create Markdown File

screenshot of website code

The next step is to convert the Google Doc version of the post to Markdown.

This section should explain the concept of transferring the reviewed Google doc into a Markdown file in a text editor. People should be directed to download Atom, then to paste into Atom, apply markdown headings and styling, link images, and be ready to use Github.

Transfer to Jekyll

close-up image of person on laptop

Published Post in Assist

The Markdown file in your Assist local folder will be synced to the Assist repository in Github. This step is a bit technical, you can however have Billy or Frank do this step for you.