Contribute

Hero image for Contribute

Compass has been thought out as a living document that constantly evolves. Nothing is set into stone. Ever. We always find better ways to do the same things or come up with entire new things to do. As a need, we need to keep Compass in sync with our processes.

How to contribute?

We πŸ’™ pull requests. If you have something you want to add or remove, please open a new pull request.

The README of the project contains information on how to:

  • Run the application in your local environment.
  • Manage the content pages and the site navigation.
  • Add assets like images and videos to the content pages.
  • Deploy a new version online.

Compass relies on Jekyll to convert Markdown content into HTML and Webpack to manage front-end assets (SVG images, stylesheets and javascript). No knowledge of either is required to contribute πŸ˜ƒ.

Contribution Guidelines

Since everyone at Nimble can contribute to Compass, we all need to follow guidelines on writing content.

Language

  • Use an active and formal tone.
  • Use American English πŸ‡ΊπŸ‡Έ.

Markdown

  • Use hyphens - for bullet lists.

    // Bad
    * This is an item
    * This is another item
    
    // Good
    - This is an item
    - This is another item
    
  • Add an image description as this is used for the alt attribute for <img />.

    // Bad
    ![](/assets/images/docs/intro/path-to/image.png)
    
    // Good
    ![Add new calendar from URL](/assets/images/docs/intro/path-to/image.png)
    
  • Use correct indent for list: type space characters in front of your nested list item (or the next lines belong to the same the list item), until the list marker character (- or *) lies directly below the first character of the text in the item above it.

    1. First list item
       - First nested list item
         - Second nested list item
    
    # OR
      
    1. First list item
       Second line of the first item
       Third line of the first item
    

UI Components

Compass UI has the following built-in HTML components to enhance the content. Use those wisely.

Callouts

Use callouts to highlight critical information on a topic.

<div class="message-notice">This is the default callout</div>
<div class="message-notice message-notice--info">This is an informative callout</div>
<div class="message-notice message-notice--warning">This is a warning callout</div>

This is the default callout

This is an informative callout

This is a warning callout

Use bookmark link to highlight important links and to point sub-pages within a top-level page.

<a href="/" class="link-bookmark">This is an important link</a>

This is an important link