SourceCred Voice

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:

  1. Community member makes a contribution to the docs (e.g. new page)
  2. 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!

5 Likes

While I onboard with your vision, the execution, i fear, is likely to be quite complicated. How would one ascertain is a piece of writing has the SourceCred voice? Who is the arbiter of this standard? Who is responsible for getting a piece of writing tuned up to meet these standards you laid out?

One possible method could be defining a a set of community roles akin to an editorial team at a news paper. An interesting possibility of developing this kind of role would be a more nuanced method for assigning grain/cred for content created (if a member of the editors “guild” likes something, it generated more grain/cred), this would outperform the simple emoji system, particularly with the inevitable increase in the size of the SC community.

2 Likes

Seth, your use of examples here is very useful, thanks for putting this work in. I agree on a lot of what you said, so I’ll just comment with things I feel haven’t been said yet.

  1. The use of metaphors are often useful in SourceCred (such as Dandelion’s thank you metaphor or Beanow’s champions v heros metaphor). I would like us to use them throughout our documents, and also be careful that they are not used instead of quality and simplistic writing. As you said about the Earning Cred page, the metaphors are good, but the writing could be improved.

  2. Your point that pages need to be rewritten several times is spot on in my experience. @rpp63 a way Seth’s proposal may be feasible is for there to be a rewriting system. A few points here:

  • Being #nit with wording often feels rude. If we agree that it’s okay and not personal to rewrite a large portion of someone’s work, that may give way to more efficient edits.

  • GitHub works really well for the editing portion of reviews, however there’s lots of waiting involved. What if we had a line of people who would send it to each other in a certain order? That way, everyone would start a doc, even just the bare bones, and then the contributions, ideas, and revamps would come piecemeal yet quickly.

  • As for the splitting of Cred, I did feel awkward about that as a rewriter. For now, if we use the system I proposed, we would be entering a large task where Cred would be equally distributed, which would be largely trust-based on effort. Maybe LB puts a lot of work into their first draft and I don’t have much to say in my review? I would hope that that would encourage me to put extra work into other documents. In the long term, I would like a different solution for the Cred being split equally, as I personally find reviewing much less effort than authoring.

3 Likes

Good proposition here, thanks! I share lots of what @Bex said :

  • the #nit guidance / rule is a must-have.

And to some extent it is valid as well for any discussion you have when you don’t get what’s being said : it’s okay & not personal to say you didn’t get it … especially if the other one is a non english native speaker (yes, I’m :fr: :grinning:)

  • the editorial team could fill this role as suggested by (@rpp63). There can be also some rotation in this editorial team so as to ensure some integrity and fairness in the arbiter role of the SourceCred voice

  • +1 for this action plan

  • my splitting Cred would be more 70%(creator)/30%(reviewer). It takes a lot more to produce than review.
1 Like

While rewriting is an important part of this, I’m more concerned with how the community will agree if if an article is up to the “SourceCred Voice” standard. So assume LB writes an article, Bex rewrites it how does the community decided Bex’s rewrite is good and/or necessary?

Good question. If LB wrote a document and I read it and wanted to change it, I could in fact create a pull request to make my own edits. I haven’t because I haven’t wanted to put in the work to create a pull request (and then wait for it to be reviewed and merged) just to fix 1 or 2 typos, as LBs documents are typically pretty spot-on. However, we don’t want any typos in our documents, and we want a consistent tone.

If it was just protocol for LB’s document to be reviewed by me, I could fix the 1-2 typos and say ‘done!’ and send it to whoever is after me. Or perhaps, I could dub it as ‘finished’ and have LB merge it to master. This way, they would still receive the Cred for creating it, and I could receive Cred by posting in Didathing. As for social etiquette, it would be expected for everything to be reviewed because no one is perfect and higher-quality writing comes from multiple edits.

I strongly agree. This is necessary to get the docs to the level of quality and consistency that I expect from us.

We can solve for this the same way we maintain our high expectations in the SourceCred codebase. In the codebase, @wchargin and myself are the maintainers, and code doesn’t get merged unless one of us have signed off on it. Currently, the docs repo doesn’t have explicit maintainers, and we’re in a more “free-for-all” model where anyone can merge approved changes to master.

We could designate a small group of people (e.g. @s_ben) as maintainers for the docs repo, and set it up so that while anyone can propose and review PRs, only the maintainers can merge them. Then, for each PR, a maintainer would work with the contributor to get it up to “SourceCred voice” quality before it merges, ensuring that the master branch (and thus our docs) are always kept to expected quality.

To make this workflow easier: it turns out GitHub lets you suggest changes directly to a pull request. Here are some examples where I suggested changes to the update earning-cred PR:

You can generate suggested changes by using starting a comment as part of a review, and then pushing this “insert a suggestion” button:

This way, the reviewer could just make suggestions with all the re-writes necessary to get to SourceCred voice. If the reviewer is a maintainer, they can even make all the suggestions, then commit the suggestions themselves, and then merge the PR themselves. Ie. this can be a fast, efficient process where someone suggests some docs, the maintainer makes all the necessary changes, and then merges it without any more need for back and forth. This should mitigate the frustrating “needs to go back and forth 5 times” issue which can make contributing on GitHub so painful.

As for Cred tracking: I think it should depend on the situation.

In the case where the change was basically fine and needed only minor changes, then the original author should get most of the Cred. We can do this by just merging the PR like normal; the reviewers will each get some Cred, and the author will get more Cred.

In the case where a contribution needed a substantial re-write to merge, then it makes sense for the author and the editors to share Cred. A simple way to do this would be to use the “paired with:” feature of our GitHub plugin. Basically, if a PR’s description includes paired with: @username in the description, then SourceCred will evenly split the Cred for authoring that PR between the original author and whoever was listed as paired-with. On GitHub, maintainers can edit PR descriptions; therefore, the maintainer can make a judgment about whether to classify it as a re-write and add the “paired with” flag.


Details may vary, but I think we need some process like the above which empowers specifically chosen maintainers to be the keepers of SourceCred voice. Going with a “democratic consensus” model will be too unwieldy, and will struggle either to maintain consistent voice, or to not get bogged down for lack of consensus.

2 Likes

By the way, I want to point to @LB’s messages in the #start-here channel of our Discord as another good example of SourceCred voice.

1 Like

Agreeing with @decentralion that the easiest way to do it is to just have have a small group of maintainers making that call. Only because while I like these more democratic ideas on paper, I think will be more complicated and may not work so well in practice, for reasons I go into below. I do think that there are ways to address the issues raised within the existing framework, and that some of these ideas can be implemented in different forms.

I think this is basically how it would work with a small group of maintainers. If the content doesn’t fit the voice–and the author can’t get it to standard with help–then the PR doesn’t get merged, and Cred doesn’t flow. I do agree we can do better than the emoji system, and that having more nuanced weightings is desirable. A “guild” makes sense. I think this is partially just due to the GitHub plugin still being mostly just activity based (in contrast to the Discourse plugin, where likes (i.e. review) determine Cred minting). I believe a long-term goal is to move the GitHub plugin away from being too activity-based. I can also see the Initiatives plugin being used here. We could, for instance, create a SourceCred Voice initiative, where Cred is minted to all contributions that corrected the Voice in another contribution. Another way a “guild” type system could be accomplished is by only allowing certain members (the editors) to mint Cred in certain domains. We’re implementing something similar for Maker where Cred can only be minted if you’re attained L2 trust level on Discourse.

Not exactly sure what’s being proposed…So let’s say I create a doc. Then it’s automatically sent to @Bex next? Then when Bex is done she sends it to @benoxmo, and so on? I fear that would only lead to more waiting. People come in and out of OSS projects a lot. They may have day jobs, go on vacation, hop from project to project, or just lose interest. In practice, I wish it weren’t this way. But having one person (or a small group) of committed people with the authority (and responsibility) to do this work is the only way I’ve seen this work get done in practice. That’s why I think Champions make sense (essentially what is being proposed here). Perhaps I’m misunderstanding. I think what you may be getting at is permissionlessness? I think we have this already built in generally. Anyone can submit a PR to rewrite content, or submit a review on a PR, make a comment, etc. All of which flow Cred.

This split feels about right to me…unfortunately, while that might be the average ratio, in practice it could vary a lot. For instance, let’s say a new contributor shows up whose PR needs a ton of work. I could spend way more time helping them that I could just rewriting it. Or, someone could submit something that only needs a couple minor changes. In this case the creator did maybe 98% of the work, and deserves more than 70%.

I think just using the paired with: @username as @decentralion suggests is a workable solution for now.

tldr; I think basically we can accomplish the desired aims using some combination of the typical OSS software development model we use on coding repos, plus the existing Chamption model and Initiatives plugin, plus creative hacks/social norms, plus new features down the line (which can be informed by data from our experience here).

Same sentiment, different syntax… I think this is the way forward. and as @s_ben said, the dream is to do this in a decentralised manner, but for now validators with a quick and easy way to do it

Indeed. Game is to remove the validators :slight_smile:

I definitely love the idea of eventually having nuanced guilds and badges of skill (which could be informed by cred as long as our measurement is nuanced enough) like an Archives Guild (documentation) with Editors, Authors, and Master Archivists, ect. with attached permissions and expectations. We’ll get there eventually, but I think our systems need a bit of time to grow first.

A lot of good comments and ideas thrown around in this thread. Again I’ll be coming in with the perspective I’ve taken from writing for Shenanigan.

I agree that having a committee of maintainers for docs is probably the best structure to obtain a voice for SourceCred. To help get it right the first time, however, one thing I believe is using character traits. At Shenanigan we have a goddess character we call SHE. SHE watches over our community ensuring fairness and correctness. We write as if SHE is watching and listening. It’s not a real technology, but it creates an idea to build off. I’m not suggesting SourceCred needs a humanoid character (in fact I think that’d be a bad idea) , but it needs some character traits. Currently, SourceCred technology feels meaty and alive, however, its also feels empty and devoid of a good hero arc. SourceCred has the Graph. Its in the logo. Maybe there is a story there. From what I read so far, the SourceCred Voice sounds a bit like an old teacher of mine that used to go snowboarding with me every other week. Informative and collected, but also just plain awesome. The Graph could be a Jarvis, meets snowboard instructor, meets Elon Musk type of entity.

I’m just spitballing here, I’m probably not the one to come up with the specific concept. But having a character or some sort of entity that people can latch onto makes a world of difference. I’m interested to what a graph would sound like if it could talk.

2 Likes