SourceCred needs a consistent “voice”. As a permissionless open soruce project, it will, in practice, have many voices. That is good! However, having a consistent voice and tone across the official docs, website and other materials is desirable. It makes the project appear more reliable and trustworthy. It is also an opportunity to express (and reinforce) our shared values.
This post is an attempt to reach consensus on the SourceCred voice. Mainly for official documentation (our most pressing need), but we could also use it to explore voice generally.
Below is my first stab at defining a voice. Feel free to push back or make suggestions!
Voice Definition
The SourceCred voice should be:
- Concise and readable (high quality writing)
- Generally casual and conversational, using 1st and 2nd person liberally. More formal and “academic” where appropriate; e.g. certain technical documentation may be more formal and use 3rd person.
- Not afraid to use unconventional or newer forms of grammar, but does so sparingly. Mainly proper English. Cool but not too cool for school. Think if MetaGame were forced to send emails at their day job.
- Accessible and respectful of readers that may not have deep technical knowledge, hail from different cultures (e.g. don’t use too many cultural specific examples or metaphors), or belong to marginalized groups (e.g. don’t assume male gender), etc.
We’re like your hip friend sitting down to patiently explain this amazing but complex technology we’re excited about. We’re not “the man” and not trying to be. But also not pretentious, willing to put in the effort to speak your language, wherever you’re coming from.
Examples
@decentralion’s post A Gentle Introduction to Cred is a good general example of the above. The below passage is friendly and conversational but still effectively conveys complex information.
Contributors—like you or me—are also nodes in the graph, and are connected to the contributions that they create. So there is an “AUTHORS” edge connecting me (the author) to this post.
You can think of each edge in the graph as being a “thank you”. Thus, this post thanks me for writing it. The “thank yous” can be bidirectional; likely your reply thanks this post for being written, and the post thanks your reply for participating with it.
Another great example is @Beanow’s seminal About Champions and Heroes post.
Why is this a tragedy?
If heroes show up, yes those heroes are amazing. We should be grateful to them. But when you think about it, having heroes is an unexpected positive outcome, when the expected result was bad . From a planning standpoint, your structure failed to prevent disaster. It worked out because of a selfless effort and luck.
What’s a champion?
“…that is what I’ve set out to do. And you can count on me to see it through to the end.” - the champion states in no uncertain terms. With a steady pace and clear message, the champion provides confidence and predictability to everyone involved. Regardless of setbacks or ethical dilemmas, the champion leads the charge, restores faith, and gets the job done.
@miyazono’s article SourceCred: an introduction to calculating cred and grain basically nails it on all fronts. It does a good job of being friendly and conversational, then dropping into a more formal, academic style when explaining more complex technical concepts. E.g., this section on CredRank:
To simplify the computational overhead and storage required to compute cred over time, SourceCred is moving toward a fibration model where a node is added per contributor, per unit time (currently a week). In this model, epoch nodes intermediate flows to a user from any nodes during a period of time and have a fixed transition probability to the user’s node, β (note that, like α, this is also a probability, not a weight).
A given user’s epoch nodes are connected to each other with transition rates γforward and γbackward, connecting forward and backward in time, respectively. These sets of edges in the Markov graph are referred to as “webbing” elsewhere. These transition rates are shown below in Figure 5.
Counter examples
Below are a couple examples of things that may need rewriting if we go with the proposed voice. Note that this is not a judgement on the writing or the writers, who are excellent!
The README @Beanow wrote for the Discord plugin. To be clear, by the standards of most OSS projects, this is GREAT documentation. It gives you all the things you need to know. It’s well written. But we might want to add some polish, make the language more consistent with other docs. We may also want to flesh out examples if appropriate, perhaps make it a little more formal…
The current Earning Cred page authored by @benoxmo is good. The work they did fleshing out the water metaphor should be very helpful to newcomers The wording could use a little tightening up though. And indeed, I see @Bex has an open PR already doing just that, which already fits the voice I’m imagining.
I think this illustrates a general process we may see play out:
- Community member makes a contribution to the docs (e.g. new page)
- If necessary, some of the text is rewritten to conform to voice. The original contributor may or may not be able to do this rewriting. We’re setting the bar pretty high as far as writing skills required; basically expecting professional writer level output, specifically tailored to our specifications. In my past experience, these things often just need to be rewriten completely. Which isn’t to say the original contribution was not valuable. Usually the original contributor does a lot of work fleshing out the overall structure, coming up with metaphors, exploring assumptions other writers are unaware of, etc.
One consequence of this process is that, as the GitHub plugin is currently configured, the original author of the doc and the rewriter will roughly split the Cred? This feels roughly OK, but wondering if anyone feels differently.
Curious to hear any thoughts!
)
