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, all contributors need to follow guidelines on writing content.

Language

  • Use an active and formal tone.
  • Use American English 🇺🇸.

Writing Point of View

The content on Compass is written and maintained by many different individuals. As a result, personal writing preferences can bring discrepancies in the language used. To minimize the variations in writing styles throughout the Compass pages, writers should always use the same point of view in their content.

Compass’s official point of view is the third person, preferably the nominative plural they.

There are two main reasons for using they:

  • It is gender-neutral.
  • It does not make assumptions about the reader.

For example:

// Bad

- When you need to run only one or a few test cases, it is unnecessary to rerun the whole test suite as that is really time-consuming. 
- We need to talk about two critical areas before anything else: respect and writing.
- There are times when the stakeholders might not know what you do, and understanding each other is difficult.
- There are times when Product will disagree with a stakeholder.

// Good

- When only one or a few test cases must be executed, it is unnecessary to rerun the whole test suite as that is really time-consuming. 
- Two critical areas must be addressed before anything else: respect and writing.
- There are times when the stakeholders might not know what the Product Manager does, and mutual understanding is difficult.
- There are times when Product Managers will disagree with a stakeholder.

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.


{% include link-bookmark.html slug="/" text="This is an important link" %}

This is an important link