How To Contribute

Writing proper documentation is hard. We need documentation that is legible, precise, unambiguous and easy to understand.

This section serves to provide basic instructions on how to organize your documentation as well as some style guidelines to keep the documentation style and language consistent across all projects.

Note

Since this is a public repository hosted on GitHub please be careful what parts of Skroutz Documentation you are exposing in the wild.

Table of Contents

Getting Started

The project is built with Middleman and documentation is written in MarkDown. So, before you start, please make sure to complete these steps:

Set up the project
Quick guide to have the project up and running locally.
Familiarize with the project structure
Though not mandatory to contribute documentation, it is highly recommended to have a quick look on how directories and files are organized.
Learn the basics of MarkDown
The kramdown lib is used by default, but there are no major differences from standard or other MarkDown flavors, e.g. GitHub Flavored MarkDown.
Familiarize with the code style
Check out how you can enrich your documentation and the rules, conventions and guidelines your contribution has to follow to be accepted.

Once, you have completed the above you may proceed to:

Add documentation
Follow the guide to add your documentation pages.
Submit your documentation
Create a new pull request.

Project Set Up

First, clone the project:

git clone git@github.com:skroutz/developer.skroutz.gr.git

Then, install the requirements:

bundle install

Finally, start serving the website locally:

FLAVOR=skroutz bundle exec middleman server

You may now point your browser at http://127.0.0.1:4567 and view the website.

Project Structure

The project file structure is based on Middleman's skeleton with minor additions for the project's needs.

The following paragraphs describe files and directories you should be familiar with.

config.rb

This is the core configuration file of the project. Consult the Middleman documentation for the available settings and options you can configure here.

data/

It contains setting files for each flavor as well as common settings across flavors.

data/docs.yml
The data/docs.yml file holds the core settings for documentation pages and it is used to generate the navigation structure of available documentations, featured documentations, etc.

lib/

It contains the custom helpers built for the project along with task files.

locales/

It contains the localization files.

resources/

It contains collections of resource files (e.g. code example snippets, API responses, etc.) needed by specific documentation pages.

resources/code_examples/

Contains large code snippets that would be difficult to maintain if placed inline the documentation. Code examples for a document should be placed within a directory with the same name that the documentation lives in. Also, you can have flavored example code snippets if necessary.

See also Add Documentation.

resources/responses/

Contains the recorded API responses for each flavor.

source/

This is where all the magic exists. In the source/ directory lives the content of the project. It contains the static pages, the documentation pages and the assets of the project.

source/assets/
Contains JavaScript, CSS, images, fonts and miscellaneous asset files.
source/localizable/
Each document lives in its own directory within source/localizable/ directory. For example, the source/localizable/analytics/ directory contains the documentation for the Analytics project.