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 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.
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:
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.
The guide draft would be a contribution to the SourceCred User Guides 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.
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.
@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.
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:
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.
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?)
I could take those info dumps and translate them into lay-person as I have space in my schedule.
We could schedule calls between us as needed to help clarify any questions I may have as I learn about each topic.
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.
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 where initiatives might be designed, approved, executed, reviewed, and finalized. 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 to an Initiative, and then how do you add that Initiative as a contribution to an Artifact? 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. 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, perhaps sooner than later. 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.
@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 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.
There’s a bunch of resources that are being aggregated in the SourceCred Protocol 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. This is why we started working on the SourceCred Codebase Walkthrough 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 that don’t translate to the way the protocol actually works.
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.
