search

sourcecred / docs

Official SourceCred documentation
https://sourcecred.io/
Other
13 stars 22 forks source link

Decide on capitalization for "cred" and "grain" #74

Open teamdandelion opened 4 years ago

teamdandelion commented 4 years ago

Throughout the docs, we should make a consistent decision on whether we should capitalize the words "cred" and "grain".

Personally, I think we probably should not capitalize them. My reasoning is that cred and grain are not proper nouns, i.e. they are not referring to a specific instance of cred or grain, but to the concepts in general. And it seems like as I review other examples, domain-specific concepts are not capitalized.

For example, in the wikipedia page on Graph theory, vocabulary words like "graph" or "edge" or "node" are not capitalized.

In the wikipedia page on Corporate finance, words like "equity", "debt", or "capital" are not capitalized.

Beanow commented 4 years ago

I have been using Cred, Grain, Initiatives in caps. Also for aesthetic but mostly to imply it's a concept rather than the dictionary meaning. Don't hold a strong opinion, but it seems convenient to me.

s-ben commented 4 years ago

Both of these arguments are solid. I've gone back and forth, and generally found I preferred capitalizing Cred and Grain, for the reasons @Beanow states. Also, words like "graph", "equity, "debt", etc. are fairly consistent across contexts, whereas our definitions of cred and grain are a bit more novel?

I think the question is: will someone reading a lowercase 'grain' in a SourceCred context (docs, articles, etc.) trip when reading because of the new meaning?

Related question: do we have a standard way to differentiate between project-specific grain and cred, and the more generalized use of the terms? Would using capitalization to differentiate here be useful? Actually, is this an argument for lowercase, as capitalization may imply more specificity than is intended in some contexts?

I don't really have a strong opinion though. The main thing is consistency.

Bex2594 commented 4 years ago

I prefer capitalizing Cred and Grain, and would feel similarly to other SourceCred concepts such as Initiatives, for the following reasons:

  1. It is aesthetically more pleasing.
  2. It is clearer to newcomers that these are concepts that SourceCred has created and named.
  3. Concepts like 'equity' and 'graph' are not specific concepts in the examples you're providing, whereas Cred and Grain are specific to SourceCred. Google capitalizes the Cloud, and now we all know what that means when it's upper case as opposed to lower.