Style guide

This is a reference guide to our documentarians. It wasn't created to limit you; instead, it should help you understand the overall style of our documentation and teach you how to reproduce it!
Language and writing style
Use inclusive language.
Write as you were having a chat with our readers. Address them directly.
Keep it simple and short: avoid jargons, long sentences and uncommon words.
When in doubt, use US English as a reference for spelling.
For headings, buttons, menu items and page names, use sentence case (as in Suggesting changes). Title case (as in Fiscal Host) should be used only when referring to features or specific roles.
Contractions
You are encouraged to use contractions as long as it doesn't make sentences difficult to read.
Use
Avoid
It's (as in 'it is'), can't, wouldn't, you're, you've, don't or do not
It is, cannot, would not, it'll, it's (as in 'it has')
Capitalization
Always capitalize the following terms:
Collective
Organization
Fiscal Host
Admin (Collective Admin, Fiscal Host Admin)
Core Contributor
When referring specifically to the feature on our platform, always capitalize:
Update
Event
Expense
Transaction
Do not capitalize the above words when they do not refer to the name of a role or entity on the platform. For example:
You can think of Fiscal Hosts as umbrella organizations for Collectives.
Fiscal Hosts and Collectives are capitalized because they refer to names of roles on the platform, but organization is not because it's used here as part of the common phrase umbrella organization.
Words to avoid
There are a lot of names and terms we have used in the past or that have common meanings close to roles and entities on the platform. It's important to use language that your intended audience will understand and identify with, so no words are banned, but be mindful of using the below terms as they can easily introduce confusion.
User
Everyone is a user, so it's not super helpful when trying to refer to something more specific.
Sponsor
This is a common word to describe when a company gives money to a project, but it _**_has caused confusion because sometimes sponsorship is defined by the kind of entity making the financial contribution (company vs individual), and sometimes it's defined by how much they are contributing (e.g. some Collectives call everything over $1000 'sponsorship' regardless of who gives it). Collectives can each define these things for themselves, so it's safer to refer to "individual financial contributor" or "organizational financial contributor".
Backer
Similar to the above. If a company gives only $5 a month, are they a backer or a sponsor? That's undefined globally, so stick with "financial contributor".
Donate, back, support, join, or any other synonym for financial contribution
Because different Collectives use different terms, the platform should not try to decide for them. Each community will have its own context. Therefore we have decided to stick with the words "contribute" and "contribution" and add the qualifier "financial" when it's through money.
Subscription
We used to call recurring financial contributions "subscriptions", but this proved problematic because most Collectives don't think of someone giving $5 a month as "subscribing" to them, and it's also easy to confuse with the concept of subscribing to Updates and getting emails. To emphasize our key action of "contribution" we call it "recurring financial contributions". We are aware this is too long, but we haven't come up with a better idea so far.
Chapter
Previously, we explored the idea of calling Open Collective branded fiscal hosts (Open Collective Europe, Open Collective UK, etc) "chapters". But this concept was not followed up and supported and using the word is confusing. These are simply Fiscal Hosts.
Formatting
Write in Markdown. To know more GitBook's implementation of Markdown, check their reference guide.
Remember to use \ any time you want to open and close parentheses ( in text.
Special attributes
Hints
1. Info
Used for neutral information.
1
{% hint style="info" %}
2
Important information!
3
{% endhint %}
Copied!
Important information!
2. Danger
Used for irreversible changes.
1
{% hint style="danger" %}
2
Danger!
3
{% endhint %}
Copied!
Danger!
3. Warning
Used for information that requires special attention.
1
{% hint style="warning" %}
2
Warning!
3
{% endhint %}
Copied!
Warning!
4. Success
Used for successful outcomes.
1
{% hint style="success" %}
2
Success!
3
{% endhint %}
Copied!
Success!
Blocks of text with tabs
1
{% tabs %}
2
{% tab title="This is the first tab" %}
3
This is a block of text with tabs!
4
{% endtab %}
5
​
6
{% tab title="And the second tab" %}
7
It could be used when there are different instructions for different operating systems.
8
{% endtab %}
9
{% endtabs %}
Copied!
This is the first tab
And the second tab
This is a block of text with tabs!
It could be used when there are different instructions for different operating systems.

Resources for documentarians

Suggesting changes

Last modified 2yr ago

Export as PDF

Copy link

Contents

Language and writing style

Blocks of text with tabs