SourceCred Language & Brand Conventions
These are proposed language & brand conventions. These guidelines helps establish a consistent voice for our documentation, website, and Wiki content. Some are general grammatical recommendations to improve clarity and understanding in language. The larger purpose is to create consistency and a shared understanding, a “being on the same page” kind of harmony between all Participants.
Why: Consistent use of these terminologies lessens the cognitive load for everyone involved, improves how well others understand what you write, and makes the project more accessible to newcomers. While this is mainly for all use on the public website and repositories of SourceCred, being consistent about them in informal channels too (e.g. Discord, Discourse) will be even more wonderful.
💖 Remember not to feel bad for doing or having done any of these in different ways! These are supportive encouragements, not punitive rules that must be adhered to. Like everything else these are subject to change over time, and already have changed in the past.
This is the name of the project itself. Write it as “SourceCred” (capital S, capital C, all else lowercase), or SC (in capitals) for short. When writing about the GitHub organization, repository, or any other code-based instance, use sourcecred (all lowercase). Do not use sc (lowercase shorthand) to refer to code-related cases where the name is sourcecred.
Any person participating in a SourceCred project is a Participant (capital P). Participants are usually people, who have one or more user accounts on the services from which data is tracked via Plugins. Any contribution that a Participant makes earns them Cred.
Participants can also be bots or organizations. For instance, any project or community that runs a SourceCred instance (other than SourceCred itself) would by default have the SourceCred GitHub organization as a Participant in that project, for the flow of Cred.
This term can be adjusted for a project to be project-specific, like “Players” in a SourceCred-powered game community, but it will still be Participant under the hood (in code).
Cred is the metric used for every contribution a Participant has made to a SourceCred project. The Cred value for each contribution is measured organically by the community members. Capitalize all use of Cred to indicate that this is a specific concept, a term with explicit meaning, and not an accidental typo of (e.g.) “credit”.
SourceCred computes a (big) Cred Contribution Graph, consisting of nodes and edges, which are the connections between nodes that flow Cred (both ways). Each Participant and contribution is an independent node. This image is a simplified example of the Cred Contribution Graph:
Grain is a community-specific digital currency (a token), issued on the basis of Cred scores. Capitalize all use of Grain to indicate that this is a specific concept, a term with explicit meaning, and not the actual agricultural product.
This measures the Cred earned by all Participants since the last cycle (default: every 6 hours), as well as lifetime Cred scores for all Participants period. SourceCred first gathers all the data via the plugins (e.g. Discourse posts, GitHub Pull Requests), then recomputes the Cred Contribution Graph.
This distributes Grain based on the Cred Contribution Graph, generally using a slower cycle (default: once a week). There are Grain Distribution Policies that govern how much Grain is awarded, and at what rate. A project can have a common funding pool for Grain and decide to use one portion of it with one policy, and a different portion using another policy.
Grain distributions can happen in more ways than one, simultaneously. Our Grain Distribution Policies allow you to issue specific amounts based on e.g. lifetime Cred scores, and other amounts based only on recent Cred scores. See our documentation for the currently supported Grain Distribution Policies.
Plugins are how SourceCred gathers and tracks the data it uses to compute its Cred Contribution Graph. Our current Plugins are:
- Discord (tracks message reactions)
- Discourse (tracks post likes)
- GitHub (tracks Pull Requests and PR reviews)
Note that Discord reactions and Discourse likes are the data points treated as contributions, which may be unintuitive.
Use the Markdown headings in documentation and wiki pages to create a consistent outline:
# Heading 1 is the page title, and should be reserved for the title field of a document or page;
## Heading 2 is for all top level sub-headings within a document, when there is more than one section;
### Heading 3…
#### Heading 4…
##### Heading 5 and…
###### Heading 6 are for sub-headings dividing a higher-level section into more than one sub-section.Use of every level consecutively is not required. For instance, this wiki page itself used to use ## (2) and #### (4) for its sections. It was only updated after it got 5 levels worth of heading nesting.
Active voice describes sentences where the subject performs the action of a verb, whereas in passive voice the subject is acted upon by the verb. (Serendipitously, the first half of that sentence is in active voice, while the second half is in passive voice.)
Example:
✅ Do use: “Join our Discord to meet other Participants.”
❌ Don’t do: “Joining our Discord will allow you to meet other Participants.”
This YourDictionary.com page on active versus passive voice explains the differences with a lot more depth and examples.
Links can be taken out of the context of their containing sentence, which is a common way that screen reader users navigate through webpages. In the active voice section above, the link text reads “YourDictionary.com page on active versus passive voice” by itself. If the link had instead been for “This YourDictionary.com page” (or worse, just “This”), it would not explain clearly where it takes the user.
✅ Make links like “Join our Discord server”
❌ Don’t make links like “Join our Discord Server by clicking here”
This same principle applies for all button labels.
✅ Do say: List positives or benefits in a sentence first, before listing the downsides or negatives.
❌ Don’t say: Avoid listing the downsides or negatives in a sentence before listing the positives or benefits.
That second example was originally written as the explanation for this. It immediately became the example illustrating the point.
Where applicable, start with the action (what you do, and how), then the action’s purpose (why you would do it), and provide context if needed.
Certain words have multiple meanings, or overlapping tenses (e.g. “lead” is both present and past tense). Avoid ambiguous interpretations wherever possible to improve reading comfort and speed, and also to accommodate people for whom English may not be a primary language.
Example: use led as the past tense of the verb to lead, to make it clear what a sentence like this means: “I lead the original Operations project.” If you led the project in the past, but not anymore, that sentence remains grammatically correct but the meaning will likely be misunderstood.
Emojis give flair and color to otherwise dry texts. They add personality, but they don’t necessarily add meaning. Be mindful not to rely on emojis to communicate critical information, as you cannot control the circumstances or technologies of another person reading this.
- ✅ Do use emoji to complement still-complete, clear (and accessible) sentences;
- ❌ Replace necessary words with emojis.
A visually impaired person or someone using screen reader technology may interpret the second item as an instruction, rather than an example of what not to do.
One of our Participants (coughFarukcough) has a tendency to write sentences that continue going like a long stream of thought, with multiple compound clauses to explain concepts just mentioned, often full of commas, and having a somewhat erratic or inconsistent flow, as a result.
Try not to do that. 👆🏼
(Transparency: Faruk wrote that sentence himself.)
Hey. Thank you for reading this. You are great. 💖