A reference for writing style and formatting
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!
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.
You are encouraged to use contractions as long as it doesn't make sentences difficult to read.
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.
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.
Everyone is a user, so it's not super helpful when trying to refer to something more specific.
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".
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".
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.
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.
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.
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.
1. Info
Used for neutral information.
Important information!
2. Danger
Used for irreversible changes.
Danger!
3. Warning
Used for information that requires special attention.
Warning!
4. Success
Used for successful outcomes.
Success!
This is a block of text with tabs!
It could be used when there are different instructions for different operating systems.
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')
Learn how to edit and add new media, pages and sections
Want to make our documentation even better? First of all, thank you! This page will guide you through our contribution process, including:
The tools we use to build our documentation
The steps you need to follow to make contributions
To edit our docs, you must have a GitHub account. If you already have one, make sure you are logged in. If you don't, please create one. We also recommend you to read our style guide before submitting any changes. It serves as a reference of our writing style and our expectations for documentation.
As collaboration in software development became more complex, involving multiple machines and developers from all over the world, the need for a tool that would help collaborators work together without much friction increased. They envisioned a tool which could:
Avoid conflicts when working with the same codebase simultaneously
Alert each developer if there were new updates to the source code before publishing new changes
Manage file differences
Help investigating what changes caused an error or a break
Revert any changes if needed
They needed a distributed version control system.
Git is one of the most popular distributed version control systems used in free and open source projects. Websites such as GitLab, GitHub or Bitbucket are some of the most popular platforms for hosting git repositories (a place where all relevant files to a project are stored). For instance, our documentation is stored in a repository called documentation on our organization profile on GitHub, opencollective. If you clone our repository (that is, make a copy our repository onto your computer), you'll copy not only all of our files but also the history of all changes (including the author ) since the repository was created!
This page will cover interactions with our repository through GitHub, the platform on which we host our projects. This is the recommended process for those who aren't familiar with Git. If you are a more experienced contributor, feel free to adopt any other workflow you want, but remember to always take into account GitBook's integration with GitHub when modifying or adding new files, sections, pages and subpages.
If you'd like to know more about Git and GitHub, we recommend Git's official documentation and tutorial and GitHub Guides.
We use a platform called GitBook to host, manage and serve our documentation. GitBook fetches files from our GitHub repository opencollective/documentation, reads them and converts them into the pages you can access on docs.opencollective.com. A generic structure of a documentation hosted on GitBook would look like this:
Its mirror to GitHub, on the other hand, would have the following structure:
The .gitbook/assets folder manages every file used in any page.
The SUMMARY.md file tells GitBook in which order we wish to display our pages and what groups there are in our documentation.
The README.md file in the main folder has the contents of the first page users see when accessing the documentation website.
Groups of pages are controlled by folders named after the group title (i.e. a-group-of-pages).
Nested pages have a similar structure to groups of pages; however, a README.md file with the contents of the parent page must be added to the folder named after the parent page title.
GitBook also created a few shortcodes for special attributes. Learn more about them reading our style guide.
1. Open the page you want to edit. What you see next depends on the resolution of your screen and whether you are viewing that page zoomed in or not.
a. On certain occasions, you may see a button saying Edit on GitHub above the Table of Contents on the right side of the page.
b. On others, you may see a GitHub icon on the top of page, next to the title and to the Table of Contents icon.
2. Click on the GitHub icon. This will direct you to the Markdown file in which the contents of the page are stored.
3. Click on the pencil icon (labeled "Edit this file"). This will open a basic editing environment in which you are able to customize aspects like line wrap and indentation.
4. Make any edits you need, remembering to always format them using Markdown. To understand better GitBook's implementation of Markdown, check their reference guide and our style guide.
5. When you are done making changes, scroll down and write a short description of your changes. Select the option Create a new branch for this commit and start a pull request and click on Propose file change. This will direct you to the Pull request page.
6. On the Pull request page, write a short comment explaining why are proposing those changes (e.g. improving readability, covering cases that weren't mentioned, adding critical details about our platform) and publish your pull request clicking on Create pull request.
Congratulations, you submitted a pull request! 🎉 Our documentation admins will review it and merge them to our documentation if approved.
Media of any kind (images, GIFs...) should be stored on the .gitbook/assets folder.
Any new media you add to the documentation should be named following this naming scheme:
Here's how it looks like for media added to the Suggesting changes page:
1. Clone our documentation repository to your account.
a. Click on the Fork button at the top of the page.
2. On your copy of the repository, create a new branch by clicking on Branch: v2, writing new-assets and selecting Create branch: new assets.
3. Click on the .gitbook/assets folder and then click on Upload files. You can drag and drop any files you wish to add or find them with your file manager clicking on choose your files. Commit your changes.
4. Open the file of the page you want to edit. To embed media to the page, write:
5. GitHub will automatically detect your new changes and give you the option to Compare and pull request. Click on it.
6. Create your pull request normally. The base repository should be opencollective/documentation using the v2 branch as the base and the head repository should be your fork using the new-assets branch as a comparison.
Please create an issue on our documentation repository to discuss your ideas before taking any action.
Go to our Issue section and click on New issue.
Describe what changes you are proposing and the motivation behind them i.e. how will them improve our documentation? How should we proceed?
Click on Submit new issue.
0. Follow the same procedure to make a copy of our documentation repository as described on the Add new images section. Name your branch new-pages, new-section or new-subpages accordingly.
1. To add a new file or folder, click on Create new file.
To create a Markdown file, remember to write the name of the file and add the .md extension.
a. If you want to add a new page to an existing section of the documentation, click on the proper folder and then click on Create new file. Name your Markdown file and start writing.
Remember: Your page will be named after the first h1 heading on your Markdown file, and not the name of the file.
b. If you want to add a new section to our documentation, click on Create new file directly. Write the name of the section and press / as many times you need. Add either a README.md file or a normal Markdown file with any name you want.
Remember: README.md creates a page with the same name of your new folder. Markdown files with any other name will create pages with a title using the first h1 heading.
2. GitHub will automatically detect your new changes and give you the option to Compare and pull request. Click on it.
3. Create your pull request normally. The base repository should be opencollective/documentation using the v2 branch as the base and the head repository should be your fork using the right branch as a comparison.
Don't forget to add any new pages to the SUMMARY.md file, and remember to link them to their source file. New unsorted pages should be added as items on an unordered list:
New sections should be added as h2 headings:
Linking other pages or sections of a page is done in a similar manner to changes to the summary.
To link another page, write:
To link a specific section of a page, write:
The text after # symbol (a hash) is an element called anchor. On GitBook, anchors are created by replacing every blank space in a section title with - (hyphens). Therefore,
Getting familiar with Git becomes #getting-familiar-with-git
Understanding GitBook's integration with GitHub becomes #understanding-gitbooks-integration-with-github
If you aren't sure how an anchor will look like, you can use GitHub to assist you: on every Markdown file, GitHub generates anchors for each section of that document. Click on the two links on the left side of the section title to see the anchor on your browser's address bar.
Sometimes you may find broken internal links. If you find one, please open an issue about it on opencollective/opencollective—we will follow up shortly.
But if you have access to the GitBook interface, here's what you should do to fix it yourself:
Check the main branch on GitHub for an old version of the page with the broken link. That will help you figure out to which page that link was originally pointing to.
Sometimes it will be just a matter of updating .gitbook.yaml to point that specific path to the right page. But other times (probably when we make aggressive changes to the folder structure—their versioning system doesn't seem to like it that much), you will have to update that link manually. To do so, hover your mouse to the old link and edit it by searching for the title of the page to be mentioned.
If you have any other questions about contributing to our documentation, please contact us or join our documentation channel on Slack.
Helping you craft a nice contribution to our docs!
Read all issues labeled documentation on opencollective/opencollective or all issues on opencollective/documentation and pick one to work on!
As of November of 2019, a release notes tool is in the works. Until it is ready, your best resource for checking if something has changed on Open Collective is reading the recently closed issues on the opencollective/opencollective repository and checking if something needs to be updated!
Did you find a typo, a broken link or image? Do you think that something could be explained better? Feel free to edit pages and submit a pull request!
Firefox offers a built-in tool that can either capture a portion of the page or the whole page you're currently viewing.
Flameshot is open-source software that helps you take screenshots easily and edit them as soon as you take them.
If Flameshot doesn't work on your Linux installation, you may want to give Shutter a shot. Shutter is also an open-source software focused on screen capture, but it isn't on active development. However, the editing tool for Shutter needs a few additional packages related to GooCanvas, a canvas widget for GTK+, to work. They should be installed in the following order:
libgoocanvas-common (translations)
libgoocanvas3 (shared library)
libgoo-canvas-perl (Perl interface)
Once you installed all of them, kill all running instances of Shutter (using the killall shutter command) and launch it again. The Edit option should become available as soon as you capture a new screenshot!
Peek is open-source software that allows you to record portions of your screen and easily transform them into GIF, APNG, MP4, or WebM.
You may stumble upon a few issues when using this software on Wayland.
GoodTwitter is an open-source extension to revert your current Twitter user interface to the old one. As of November of 2019, Twitter has unveiled their new interface and the embedding code they now offer doesn't work as intended on GitBook. To be able to embed tweets as seen on the Sustainer Resources page, you will need to access the old UI.
GoodTwitter is available for Google Chrome and Mozilla Firefox.
Do you have any suggestions of tools documentarians could use on this OS? Please edit this tab!
Do you have any suggestions of tools documentarians could use on this OS? Please edit this tab!
