Add Documentation Edit the file on GitHub

Follow this guide to add a new documentation.

Table of Contents

Introduction

We'll use the Analytics project as an example to guide you how to add a new documentation section.

Documentation Directory

The first step you have to do is create the directory that the documentation will live in and be served from.

The documentation directory name should be comprehensive, representative and future proof. Keep in mind that it will be part of the URL path to access the documentation.

Avoid flavored names
Do not use flavored names (i.e. alve, scrooge, skroutz, etc.) for the documentation directory, even if your project is only available for a single flavor. It will make things a lot easier to maintain if something changes in the future.
Group when appropriate
If your project consists of sub-projects with separate documentations then you should try to group them under a common directory.

Some bad documentation directory names are:

- cost-per-action   # Consider `cpa` or `cost_per_action`.
- skroutzeasy       # Avoid flavored names. Consider `easy`.
- api_v3            # Consider grouping, `api/v3`.
- elasticsearch-skroutz-greekstemmer    # Too long and flavored. Consider `elasticsearch/stemmer`.
Example

For the Analytics project, a sane choice for the directory name would be analytics. The documentation will live in:

source/
+-- localizable/
    +-- analytics/

and it will be accessible at:

https://developer.skroutz.gr/analytics/

Index page

Each documentation directory should serve an index page.

Example

For the Analytics project we create the index.html.md.erb inside analytics/ directory.

source/
+-- localizable/
    +-- analytics/
        +-- index.html.md.erb

Other pages

To add a documentation page just create a new file <name>.html.md.erb inside your documentation directory.

Example

For example, we need the documentation of the Analytics Settings API to be a single page within the Analytics documentation. To achieve this, we create the settings.html.md.erb inside the analytics/ documentation directory:

source/
+-- localizable/
    +-- analytics/
        +-- index.html.md.erb
        +-- settings.html.md.erb

that will be accessible at:

https://developer.skroutz.gr/analytics/settings/

Sidebar Entry

The sidebar is auto-generated based on syntax and naming conventions. To have the documentation appear in the sidebar:

  1. Update data/docs.yml with a new entry of your documentation pages
  2. Update locales/ with the missing translations for all flavors

Update data/docs.yml

Add a new entry for your documentation and define which pages should be visible at the sidebar.

The data/docs.yml file holds the documentation structure. Each root element defines a different documentation.

The schema of a data/docs.yml root element is the following:

mydoc:
  base: '/mydoc/'
  featured: true
  icon: 'fa-bug'
  pages:
    - { title: 'overview', url: '/mydoc/' }
    - { title: 'doc_page_name' }
Note

Make sure to update locale files with the missing translations.

Attributes
Name Type Required Description
base String Yes The path to the documentation directory, e.g. 'analytics/'.
deprecated Boolean No Set to true to label a documentation as deprecated.
featured Boolean No Set to true to make the documentation featured in the home page.
flavors Array No Define which flavors the documentation will be available in.
icon String No A FontAwesome icon to accompany the documentation. This is required in case of a featured documentation.
pages Array No Define the pages to show in the documentation.
Root keys are unique
Obviously you should not use the same root key for different documents. If the one you have selected is already taken, stop whining and pick another one. Perhaps it's time to consider why that key was taken, find the team responsible by runninggit blame on data/docs.yml and discuss the issue with them.
Order matters
The order of root keys is also the order that documents will appear in the sidebar (and other places too, e.g. featured documentations, documentation page, etc).
Pages
Each pages entry is an inline collection with a required key title. The title value should match the page filename. For example, for the analytics/settings.html.md.erb page, the pages entry should be:
- { title: 'settings' }
The title value is also the key to the localization of the page title.

As a convention, the first pages entry should be the index page. It must set the url key to the base of the documentation. For example:
- { title: 'overview', url: '/analytics/' }
For consistency, the index page should have the title overview.

If you need to link to an external page resource, set it with the url key:
- { title: 'settings', url: 'http://www.example.com/' }

Example

The entry for the Analytics documentation is:

analytics:
  base: '/analytics/'
  featured: true
  icon: 'fa-bar-chart-o'
  pages:
    - { title: 'overview', url: '/analytics/' }
    - { title: 'settings' }
    - { title: 'ecommerce' }

Update locales/

After updating the data/docs.yml with the documentation pages, it is required to update the locale files with the missing translations.

Example

For the Analytics project, we update the locales/en.yml locale with the analytics parent title translation under the titles section:

titles:
  analytics: 'Analytics'

and the proper translations for each of the documentation pages under the docs/analytics section:

docs:
  analytics:
    short_description: 'Analytics is a platform that...'
    overview: 'Overview'
    settings: 'Settings'

Localization

By default documentation is served in the English language for each flavor. Define the locale property at the page frontmatter section to make it available in multiple languages for a given flavor.

Locale
You should define the proper locale rules for each of the translated pages, otherwise you may end up with inconsistent page links.
Example

Define available locales at the frontmatter section.

---
locale:
  alve:
    - 'en'
    - 'tr'
  scrooge:
    - 'en'
  skroutz:
    - 'en'
    - 'el'
---

and render the available page_locales partial to notify the users that the page is available in multiple locales.

<%= partial 'partials/page_locales' %>