# SourceCred User Guides **URL:** \ **Category:** Initiatives\ **Tags:** 🏗️in-progress\ **Created:** [December 26, 2019, 11:58pm UTC](https://discourse.sourcecred.io/t/sourcecred-user-guides/473 "2019-12-26T23:58:26Z")\ **Posts on this page:** 10\ **Page:** 1

**Author:** ![burrrata](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/burrrata/32/135_2.png) [@burrrata](https://discourse.sourcecred.io/u/burrrata)\ **Post date:** [December 26, 2019, 11:58pm UTC](https://discourse.sourcecred.io/t/sourcecred-user-guides/473/1 "2019-12-26T23:58:26Z")

# Description * * * Currently we’re building the SourceCred game as we play. Now that we have a few of the basic components figure out, however, it makes sense to document them. This will help us refine our own thinking while also making it possible for others to join us 🙂 # Status * * * Championed and in progress. # Champion * * * @burrrata and @LB are co-championing this Initiative # Review * * * This Initiative has not yet been reviewed. (review process TBD) # Benefits * * * Currently not even the most active SourceCred contributors fully understand how SourceCred works. documenting the basic game-play mechanics will help us collaborate more effectively via the SourceCred protocol. This will then help us update the game as we dogfood it. It will also help others join us if they want to play too. # Implementation Plan * * * Read through all the posts on the forum, organize relevant content, and distill game-play mechanics into a field manual for SourceCred. # Deliverables * * * A [Getting Started](https://discourse.sourcecred.io/c/the-credsperiment/getting-started/20) category will be created to help people start playing. This will include, but not be limited to: - a “SourceCred in 5 minutes” guide that attempts to onboard new users in 5 minutes or less - a SourceCred overview doc that takes 10-20 minutes to read and explains all the core components of SourceCred - user guides on how to play SourceCred on various platforms such as Discourse, GitHub, Twitter, etc… > Note: we will create separate Initiatives to create user guides for specific mechanisms such as Initiatives or Boosting and those guides will then be the Description content of the Artifacts of those things. # Dependencies * * * The code for Supernodes (and thus Initiatives and Artifacts) needs to be solid. SourceCred gameplay on various platforms needs to be stable. # References * * * # Contributions * * * > [@SourceCred in 5 minutes](https://discourse.sourcecred.io/t/sourcecred-in-5-minutes/466/): > > What is SourceCred? SourceCred is a reputation protocol for open collaboration. At a basic level, SourceCred tracks the contributions that are made to a community project. It does this by assigning each contribution and contributor a score, called “Cred”, based on the contributions’ value to the project. You can think of SourceCred as turning community collaboration into a game. To earn high Cred scores you need to make contributions that the community values. SourceCred itself is dogfooding S… > [@SourceCred: a very high level overview](https://discourse.sourcecred.io/t/sourcecred-a-high-level-overview/382/): > > For a more practical and up to date guide on SourceCred please see [SourceCred in 5 minutes](https://discourse.sourcecred.io/t/sourcecred-in-5-minutes/466) SourceCred is a protocol for open collaboration. It allows you to easily reward and recognize contributions. Let’s explore why this matters and how it might work. If a tree falls in a forest and no one hears it, did it make a sound? If an act of kindness warms a heart, but no one was able to measure it’s impact did it really have value? These are the questions that keep us up at night. These are also… > [@Playing The SourceCred Game On Discourse](https://discourse.sourcecred.io/t/playing-the-sourcecred-game-on-discourse/388/): > > Current stage: brainstorm brain[SourceCred in 5 minutes](https://discourse.sourcecred.io/t/sourcecred-in-5-minutes/466) covers how to play SourceCred from a generic perspective, and this guide covers how to play specifically on this Discourse forum. General Discourse Stuff [Discourse](https://www.discourse.org/) is an amazing forum software that lets you do all sorts of things. While it’s powerful, it can also be confusing. We’ll do our best to cover some the features that SourceCred uses the most, but if you’re new to Discourse we recommend the [Discourse New User Guide](https://meta.discourse.org/t/discourse-new-user-guide/96331). To Do … > [@Cred: not a token](https://discourse.sourcecred.io/t/cred-not-a-token/465/): > > Placeholder text that is at least 20 characters. > [@Grain: a project-specific, cred-powered token](https://discourse.sourcecred.io/t/grain-tokens-to-play-the-sourcecred-game/147/): > > A big part of SourceCred’s vision is the desire to create project-specific cryptoassets, called ‘Grain’, which represent contribution to or support of a project. Here’s an overview, as lifted from [my own writings on GitHub](https://github.com/sourcegrain/mission). SourceGrain SourceGrain will make open-source software projects financially sustainable by letting them issue their own project-specific cryptoassets, called grain. Properties of Grain Grain is always project-specific. For example, “SourceCred grain” and “IPFS grain” would… > [@Boosting: a prediction market on ideas](https://discourse.sourcecred.io/t/boosting-a-prediction-market-on-ideas/306/): > > Overview Boosting is a mechanism that allows people in the community to express that they believe a contribution is undervalued; that is to say, that a contribution is receiving too little Cred. In order to boost something, the booster must have Grain. They can then “plant” the Grain in order to Boost the contribution. That causes the Cred of the contribution to increase, in proportion to the amount of Grain that was planted. The fact that Grain was planted is crucial; it means that Boosting i… [https://discourse.sourcecred.io/t/initiatives-things-that-make-sourcecred-better/471/](https://discourse.sourcecred.io/t/initiatives-things-that-make-sourcecred-better/471/) > [@Artifacts: things that provide ongoing value](https://discourse.sourcecred.io/t/artifacts-things-that-provide-ongoing-value/474): > > Placeholder thread for Artifacts docs and user guides > [@Create A Beginner’s Guide to Initiatives](https://discourse.sourcecred.io/t/create-a-beginner-s-guide-to-initiatives/521): > > Description I’d like to create a document that is a Beginner’s Guide to Initiaives. This guide would use clear, concise language to explain what an Initiative is, how it’s used in SC, and how to create one. It would also become one of multiple guides within the Getting Started Category. Status Championed (In Progress) Champion@LB Benefits Having a Beginner’s Guide to Initiatives would enable and empower beginners to get involved with the community, understand the larger values of t… ---

**Author:** ![burrrata](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/burrrata/32/135_2.png) [@burrrata](https://discourse.sourcecred.io/u/burrrata)\ **Post date:** [December 30, 2019, 4:15am UTC](https://discourse.sourcecred.io/t/sourcecred-user-guides/473/2 "2019-12-30T04:15:14Z")

Originally my intention was to create a Getting Started category and then explain how stuff works there. This is becoming a bit tricky, however, because then when linking to things I’m not sure if I should link to the user guide (informative) or the Artifact (best for Cred flow). It seems like it would make more sense for all the information about a thing to be in one place. With that in mind, would it maybe make sense to draft the user guides in their own threads, but then add the content to the “Description” section of Artifacts. This way linking UX and Cred flow would be improved. Also, users would be able to see how a concept/mechanism works, but would also have more information right there if they want to learn more or contribute to improving the Artifact. This would result in the Getting Started category (initially) consisting of: - [SourceCred in 5 minutes](https://discourse.sourcecred.io/t/sourcecred-in-5-minutes/466/) - [A Living History of SourceCred](https://discourse.sourcecred.io/t/a-living-history-of-sourcecred/310/) - [SourceCred Mega Thread](https://discourse.sourcecred.io/t/sourcecred-mega-thread/381/) - SourceCred Discourse Guide - SourceCred GitHub Guide - SourceCred Discord Guide - SourceCred ABC Channel Guide The SourceCred in 5 minutes as well as the SourceCred Mega Thread would link to all the relevant Artifacts. All of the user guide draft threads would be moved to the #community:didathing category. The actual content of the guides, however, would be moved to the `Description` category of the Artifact relating to that thing. Then further improvements to the guides/information (and discussions about those improvements) would happen in the Artifact thread. This way anyone wanting to contribute would be able to see all the information for an Artifact in one place. ---

**Author:** ![decentralion](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/decentralion/32/7_2.png) [@decentralion](https://discourse.sourcecred.io/u/decentralion)\ **Post date:** [December 30, 2019, 5:49am UTC](https://discourse.sourcecred.io/t/sourcecred-user-guides/473/3 "2019-12-30T05:49:16Z")

> [@burrrata](#): > > With that in mind, would it maybe make sense to draft the user guides in their own threads, but then add the content to the “Description” section of Artifacts. Is this an artifact for the guide, or an artifact for the thing the guide is describing? > [@burrrata](#): > > - SourceCred ABC Channel Guide What does this mean? ---

**Author:** ![burrrata](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/burrrata/32/135_2.png) [@burrrata](https://discourse.sourcecred.io/u/burrrata)\ **Post date:** [December 30, 2019, 6:17pm UTC](https://discourse.sourcecred.io/t/sourcecred-user-guides/473/4 "2019-12-30T18:17:22Z")

> [@decentralion](#): > > > With that in mind, would it maybe make sense to draft the user guides in their own threads, but then add the content to the “Description” section of Artifacts. > > Is this an artifact for the guide, or an artifact for the thing the guide is describing? The guide draft would be a contribution to the [SourceCred User Guides](https://discourse.sourcecred.io/t/sourcecred-user-guides/473) Initiative. Then the guide would be added to the Description section of the Artifact for that thing (Boosting, Initiatives, etc…). That way users can just always link to the Artifact and all the info (and Cred flows) can be in one place. > [@decentralion](#): > > > - SourceCred ABC Channel Guide > > What does this mean? Any other arbitrary communication channel we may or may not add in the future. Since game mechanics will be different across platforms, it seems important to have platform specific guides to explain those differences. ---

**Author:** ![burrrata](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/burrrata/32/135_2.png) [@burrrata](https://discourse.sourcecred.io/u/burrrata)\ **Post date:** [December 31, 2019, 12:00am UTC](https://discourse.sourcecred.io/t/sourcecred-user-guides/473/5 "2019-12-31T00:00:02Z")

@LB Added you as co-champion and updated the Initiative to reflect our conversation earlier today. Please feel free to edit and update the Initiative as desired. Also, we should sync up sometime soon to figure out how we want to collaborate on the overall strategy for this Initiative. ---

**Author:** ![LB](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/lb/32/1079_2.png) [@LB](https://discourse.sourcecred.io/u/LB)\ **Post date:** [January 5, 2020, 11:29pm UTC](https://discourse.sourcecred.io/t/sourcecred-user-guides/473/6 "2020-01-05T23:29:36Z")

Hey hey! Had a short chat with DL and wanted to reach out to orient on how we could tackle the User Guides Initiative in a way that works best for us @burrrata . 🙂 Lately the CredCon stuff has really grabbed onto my attention by virtue of its deadline, so I see the User Guides taking a sort of backseat to that. Still important and still on my brain, but with less urgency. So I’m saving my User Guide writing time for when CredCon stuff isn’t banging on my door (like right now, while I wait for folks to fill out the Registration Form). I had a couple thoughts on a workflow we could use to collaborate on User Guides, and am curious to hear how it resonates with you: 1. We could choose a handful of topics for the User Guides category which we think are important, and create an initiative for each that we co-champion. 2. You could work at your own pace creating info-dumps for each of the Guides we’ve chosen. (Probably as its own topic that links back to the initiative?) 3. I could take those info dumps and translate them into lay-person as I have space in my schedule. 4. We could schedule calls between us as needed to help clarify any questions I may have as I learn about each topic. 5. Publish each User Guide as it’s finished. (Probably also as it’s own topic which links back to the initiative?) Let me know what you think! Happy to hear other workflow suggestions, or improvements to what I’ve described above. I definitely want to find a workflow that takes both our needs/styles into account as we co-champion the User Guides Initiative. 🙂 -LB ---

**Author:** ![burrrata](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/burrrata/32/135_2.png) [@burrrata](https://discourse.sourcecred.io/u/burrrata)\ **Post date:** [January 7, 2020, 5:37am UTC](https://discourse.sourcecred.io/t/sourcecred-user-guides/473/7 "2020-01-07T05:37:34Z")

Overall this sounds good. The problem is that lots of the mechanisms are still evolving. For example: Initiatives. Initially Initiatives were just a way to organize information for people to self select and opt-in to contributing value in ways that aren’t measured by raw activity. Now we’re talking about a [review culture](https://discourse.sourcecred.io/t/spontanious-community-call/543) where initiatives might be [designed, approved, executed, reviewed, and finalized](https://discourse.sourcecred.io/t/changing-the-credsperiment-weights/540/25). This is very different than just creating a task and giving it a good try! Then there’s also the format of Initiatives: how do you go from a [brainstorm](https://discourse.sourcecred.io/t/about-the-initiatives-wish-list-category/311) to an [Initiative](https://discourse.sourcecred.io/t/about-the-initiatives-category/242), and then how do you add that Initiative as a contribution to an [Artifact](https://discourse.sourcecred.io/t/artifacts/507)? In a review culture who has the authority on this and how are decisions made? There’s lots of moving pieces. TBH these guides can’t be finished until the CredSperiment is finished. Until then, just like the CredSperiment is a train laying the tracks as it goes, user guides and documentation is a constant WIP. When I originally created this Initiative it was based on documenting SourceCred as we know it today. In the last few weeks, however, there’s been a big push to move away from raw activity and towards [Supernodes: Moving past raw activity](https://discourse.sourcecred.io/t/supernodes-moving-past-raw-activity/340). As a result, I dunno if we’re ready for SourceCred user guides anymore. Most of the back-end code for the SourceCred mechanisms are still in the design phase and haven’t even been built yet. In addition, while we’re currently using the front-end of GitHub and Discourse we’re going to start [SourceCred UI Design and Development](https://discourse.sourcecred.io/t/sourcecred-ui-design-and-development/470), perhaps [sooner than later](https://discourse.sourcecred.io/t/changing-the-credsperiment-weights/540/26). This all translates to lots of changes in the near future. Curious to hear what you think about all this, but my impression is that we will have higher returns on effort if we wait until the dust settles a bit rather than trying to define things that are still in the brainstorming phase. ---

**Author:** ![decentralion](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/decentralion/32/7_2.png) [@decentralion](https://discourse.sourcecred.io/u/decentralion)\ **Post date:** [January 8, 2020, 3:20am UTC](https://discourse.sourcecred.io/t/sourcecred-user-guides/473/8 "2020-01-08T03:20:17Z")

> [@burrrata](#): > > Curious to hear what you think about all this, but my impression is that we will have higher returns on effort if we wait until the dust settles a bit rather than trying to define things that are still in the brainstorming phase. @burrrata makes a very good point. A lot of the specific user-facing mechanics are still very early prototypes, so investing a lot in documenting them right now is premature. Instead, we should focus on documenting the core concepts. A major thing I noticed while reading @LB’s [draft initiatives guide](https://discourse.sourcecred.io/t/draft-initiatives-guide/525) is that trying to explain initiatives to someone who doesn’t understand how Cred works is going to be a struggle. Fortunately, the core mechanics of SourceCred are pretty stable at this point. So maybe the next step is to write a beginners guide to SourceCred, which explains how Cred works, with illustrated examples? There have been a few attempts at this so far (including my talks, and some of @burrrata’s posts), but nothing that’s pass the quality bar to become a definitive artifact. What do y’all think of this direction? It would be great to have a high quality guide in time for CredCon / ETHDenver. ---

**Author:** ![burrrata](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/burrrata/32/135_2.png) [@burrrata](https://discourse.sourcecred.io/u/burrrata)\ **Post date:** [January 9, 2020, 3:13am UTC](https://discourse.sourcecred.io/t/sourcecred-user-guides/473/9 "2020-01-09T03:13:26Z")

> [@decentralion](#): > > the core mechanics of SourceCred are pretty stable at this point. So maybe the next step is to write a beginners guide to SourceCred, which explains how Cred works, with illustrated examples? There’s a bunch of resources that are being aggregated in the [SourceCred Protocol](https://discourse.sourcecred.io/t/sourcecred-protocol/500) Artifact. The thing is that “Cred” is really really closely tied to (and really a part of) the actual “SourceCred protocol.” As such, it’s important to also understand the [SourceCred Technical Specification](https://discourse.sourcecred.io/t/sourcecred-technical-specification/494). This is why we started working on the [SourceCred Codebase Walkthrough](https://discourse.sourcecred.io/t/sourcecred-codebase-walkthrough/551) so that it’s easy to understand how the code works, then we can document the protocol, and then we can explain how Cred works at a high level. Otherwise we’re just throwing around [vague metaphors](https://discourse.sourcecred.io/t/sourcecred-a-very-high-level-overview/382) that [don’t translate to the way the protocol actually works](https://discourse.sourcecred.io/t/questions-about-initiatives/443/8). ---

**Author:** ![decentralion](https://yyz2.discourse-cdn.com/flex032/user_avatar/discourse.sourcecred.io/decentralion/32/7_2.png) [@decentralion](https://discourse.sourcecred.io/u/decentralion)\ **Post date:** [January 9, 2020, 8:05pm UTC](https://discourse.sourcecred.io/t/sourcecred-user-guides/473/10 "2020-01-09T20:05:13Z")

Also a good point. I’m doing a bit of algorithm cleanup, to separate the core cred calculations away from any dependency on plugin code. (As a happy side effect, this will also enable plugins to set custom cred weights on individual nodes–as is needed for the initiatives and artifact plugins.) Then, I’m going to write a first written guide to the algorithm, with code examples. This will unblock @anon60584824 on making a python implementation, and should unblock the first canonical explanation of what Cred is.