tinok/help

The Help Site is a site that contains useful documentation on using the new Ona platform.

Following the Help site outline the guidelines below should help one upload content on the site:

Setting up GIT
Setting up Jekyll
Creating Branches
Documentation Collaboration
Markdown structure
Screenshots

Setting up GIT

The Help site is hosted on Github pages, thus all development goes through the onaio/help github repository. Install Git and clone the Help site source as explained below:

Setting up locally:
Install GIT;
Set up your GIT installation;
Cloning Help site from repository:
In your command line/ terminal, type git clone git@github.com:onaio/help and press Enter. Wait till cloning has completed;
Change into the help directory created and start adding content, refer to Documentation Collaboration;
To view your changes you will need to install Jekyll.

To learn Git, refer to the documentation here.

Setting up Jekyll

Install the following dependencies to enable jekyll installation. Installations of each requirement may vary depending on OS. Programs like Ruby may already to be installed in MacOS and Linux distributions, with Windows being the exception.

Setting up Jekyll locally by installing the following:
Node
Ruby
Ruby Gems
Ruby-dev utils
Jekyll
Running the help site locally
Once you have successfully installed Jekyll, navigate to the Help Folder and run jekyll serve --watch;
Jekyll has a number of options when serving the site:
- jekyll serve : Runs the Jekyll site without autobuilding changes;
- jekyll build: Builds a Jekyll static site in the _site folder, generated in the Help site directory;
- jekyll serve --watch : Runs the Jekyll site in auto-build mode, where changes to files can be automatically run on refreshing the page on your browser.
- More options are available at Jekyll docs;
Go to http://localhost:4000 on your browser to view the site;
You can now edit the changes using a Markdown editor such as Brackets.

Creating Branches

Any documentation that is to be added will be created as an issue on Github. This means that:

The branch should be based on issues assigned;
Issue number should be at the beginning of branch name and hyphen separations e.g. 34-issue-title-with-hyphen-separators
Making pull requests for QA to be done.

Documentation Collaboration

Use Google Docs for documentation sections before adding to Markdown. Google doc content should be saved in their specific guide folder as indicated here;
Docs should be reviewed and edited to ease addition to Markdown. After working on the content share the link on the assigned issue.

Markdown structure

Use blockquotes for important points;
All screenshots should be inserted without any line breaks before/after (margins will be handled in CSS)

For guidelines on using Markdown, see the documentation at http://daringfireball.net.

Screenshots

Use Skitch to highlight images;
Use lines/pointer arrows having the HEX colour code #FF2E6C;
Use rectangles to highlight;
Use the second brush-size in the Skitch tools panel;
Resize your browser to increase visibility of detail;
All images should be saved in content/screenshots/guide-name folder (with guide-name being the name of the respective guide).
On the markdown file, add the image URL e.g. /content/screenshots/guides/getting-started/how-ona-works.jpg (NOTE: the URL starts with a slash '/' )

tinok / help