Documentation Matrix

This is a collection of existing SourceCred documentation, created to help organize ongoing documentation efforts.

If there’s a piece of documentation I’ve missed, feel free to add it!

Published docs

Document Description Status Notes
Official docs Official SourceCred documentation. Hosted on a static site powered by Docusaurs. Source files live at sourcecred/docs Docs have a few things fleshed out (glossary, concepts, code of conduct, review culture), but are fairly rough (e.g. some broken links) and there are some big missing pieces, depending on how much we want to put in official docs vs GitHub READMEs, articles, etc. (e.g. more fleshed out intro to SourceCred, how to guides, description of the architecture, plugins, etc.)
sourcecred README Instructions on building and configuring SourceCred, typical of an OSS project. The README also has a high-level intro to SourceCred, a call to action for early adopters, and instructions for new contributors. The instructions for building and configuring SourceCred appear to be mostly up-to-date (though could use some testing and likely bug fixing). There may be things that haven’t been documented yet (e.g. new features). The high-level intro to SourceCred, ‘Current Status’, ‘Early Adopters’ and ‘Contributing’ sections probably need updating to reflect current project status and thinking, and may be moved elsewhere (e.g. official docs), depending on our docs stragegy. IMO (@s_ben) this README has grown quite large. Now that we have the static site launched, I’m thinking a lot of this could be moved there, including much of the technical documentation and general project descriptions.
Plugin documentation Each plugin is documented in a README under that plugin’s directory in the main sourcecred repo, e.g. the GitHub plugin is at: /sourcecred/src/plugins/github.

This is mainly technical documentation, detailing the data structures, instructions on configuration, etc., mixed with some “user docs”.
Plugins currently documented: GitHub plugin, Identity plugin, Discord plugin

Plugins not documented: Initiatives plugin (Issue), Discourse plugin (Issue)
IMO (@s_ben) plugin technical documentation seems like a better fit in the official docs. It may make sense to split user documentation and technical documentation depending on docs strategy.
SourceCred algorithm High-level documentation of the SourceCred algorithm. Hasn’t been edited in some time, may be out of date. IMO (@s_ben) parts of this may be out of date, but there’s some solid writing here that we might be able to reuse elsewhere.
SourceCred: an introduction to calculating cred and grain Article written by @miyazono and published on the @protocol site that explains the basic mechanics and architecture of SourceCred. We have already used parts of this as raw material for explanations of cred and grain in the offical docs. Presumably linked to in other places as well. IMO (@s_ben) this doc does a lot of heavy lifting in explaining pretty complex concepts. I think we can probably leverage it more in official docs, other materials.
SourceCred medium A collection of articles explaining SourceCred, research, and case studies:

Introduction to SourceCred

Exploring Subjectivity in Algorithms

Network Formation Games

DAOs and the Missing Link: Reputation Protocols
Articles are linked to in various places. They seem mostly up-to-date, despite being a bit old, due to their generally evergreen nature. Might need a refresh here and there. IMO (@s_ben) we definitely want to leverage this high-quality material. At least by linking to it where appropriate
Video walkthrough of codebase Screencast recorded at CredCon giving a walkthrough of the SourceCred codebase There was talk of uploading to YouTube, but not sure where we landed on this… IMO (@s_ben) this is likely a valuable asset that should be used somewhere

Documentation in Discourse posts

We have a lot of documentation scattered in Discourse. Some of it is out-of-date, but perhaps contains valuable content that can be repurposed in official docs or elsewhere.

Document Description Status Notes
Documentation glossary and wishlist Wishlist for inclusion in glossary Hasn’t been updated in a while, but it looks like there are a couple items on the wishlist not done yet…
Create A Beginner’s Guide to Initiatives @LB fleshed out an Initiative for a beginner guide to Initiatives This is a bit old now, not sure where it landed…
SourceCred User Guides @burrata fleshed out an Initiative for user guides Hasn’t been followed up on in a few months, there’s some docs strategy discussions in the comments…
Trust levels @wchargin post on trust levels. Has been translated into a PR on sourcecred/docs, is awaiting merge.
A Gentle Introduction to Cred High-level introduction to SourceCred May be a bit out of date. Still linked to from the sourcecred/sourcecred README, possibly elsewhere
Boosting High-level introduction to Boosting This is a bit old now, not sure where it landed…May be some reusable text here
Boosting: a prediction market on ideas Description of the mechanics of boosting. Likely a bit out of date, but there are some clear explanations and much of the content may be re-usable elsewhere
SourceCred Beta and Pilot Partnerships Description of the partner program. Not sure where this would go or be used elsewhere, but documents well the type of support SourceCred can support
Initiatives Description of Initiatives Hasn’t been updated in a while, but could provide a good high-level description for this concept in the official docs or elsewhere
About Champions and Heroes Description of Champions and Heros, a key concept in SourceCred that is on the Documentation glossary and wishlist Not sure if this content has already been used elsewhere…

Docs strategy posts

Document Description Status Notes
Comment on codebase walkthrough @wkarshat lays out topics they would personally like to see covered Hasn’t been followed up on
Document the core architecture Issue on GitHub where @decentralion and @wchargin discuss how to document the SourceCred architecture and give thoughts on docs in general Very old (Oct 2018), but there appear to be some solid ideas that may still be relevant to current docs efforts
Required documentation for releases @Beanow suggestion that documentation for new features must be included in the software release. IMO (@s_ben) this is the most efficient way to create the documentation, as the material is fresh in the dev’s mind, and getting it later from them is costly, to the dev and the writer of the docs.
4 Likes

Yeah, I think we’re going about Initiatives pretty differently now. However the guide draft could hold some useful reflections to springboard off as we create a new system for how people should engage with creating/contributing to initiatives.

That link goes straight to my old Initiative, here’s the link to the draft of the beginner’s guide:

Also, this is incredible @s_ben! Super impressed you were able to wrangle all of these chaotic docs into something cohesive and useful! It’s going to be so helpful in the Docs meeting we have coming up.

1 Like

Oh, I have some documentation starters on Roam. Should I add them in the comments here, or create a Roam section this post/topic itself @s_ben ?

You should be able to add yourself @LB. I think all posts are editable wikis by default, for now. Though I don’t think edits flow cred, something to keep in mind.

1 Like