Contribute

Every team member can contribute to Compass. This document provides guidelines for contributors to make changes effectively.

How to contribute?

The team 💙 pull requests. To suggest changes, please open a new pull request.

The README of the project contains information on how to:

• Run the application in the 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.

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:

- 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.

- 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.

  * This is an item
  * This is another item

  - This is an item
  - This is another item

• Add an image description as this is used for the alt attribute for <img />.

  ![](/assets/images/docs/intro/path-to/image.png)

  ![Add new calendar from URL](/assets/images/docs/intro/path-to/image.png)

• Use the correct indent for the list: type space characters in front of the nested list item (or the following lines belong to the same 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>

Bookmark Links

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

Code Block Styles

Use code block styles to highlight the good code and the bad code on the code convention page.

<div class="code-block code-block--good">
```language-identifier
This code is good! Do write this
```
</div>

This code is good! Do write this

<div class="code-block code-block--bad">
```language-identifier
This code is bad! Don't write this
```
</div>

This code is bad! Don't write this

Inline Attribute Lists Syntax

Use the inline attribute lists syntax to apply built-in HTML components of Compass UI.

This inline attribute lists syntax works for single-line content (one paragraph). More than one paragraph of content would not work.

Examples:

{:.message-notice}
This is the default callout

This is the default callout

{:.message-notice.message-notice--info}
This is an informative callout

This is an informative callout

{:.message-notice.message-notice--warning}
This is a warning callout

This is a warning callout

{:.code-block.code-block--good}
```language-identifier
This code is good! Do write this
```

This code is good! Do write this

{:.code-block.code-block--bad}
```language-identifier
This code is bad! Don't write this
```

This code is bad! Don't write this

Images

Using images is a great way to enrich the content and, as the saying goes, “a picture is worth a thousand words.”

There is a right way to use images, though. Images will slow down the page’s loading speed if not used right.

Two things should be done to an image before committing it to Compass:

1. Resize it to an appropriate size (e.g., 1024px wide). The aspect ratio must be maintained.
2. Optimize the image (e.g., to adjust the level of quality necessary and remove useless metadata).

To resize an image, there are usually tools built into all computer’s operating system. MacOS’s Preview, for example, allows for resizing images (via Tools > Adjust size...).

For image optimization, TinyPNG is a fantastic tool.

There is no hard requirement regarding image types. WebP and JPEG are usually the most appropriate image types for the web.