Documentation Matrix

[s_ben]

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.

[LB]

@s_ben

|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…

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:

[DRAFT] Initiatives Guide

[META: This is a draft of a guide for new community members to learn about what an initiative is, and how to create one. This document will be added to and expanded on the more I read and metabolize topics related to Initiatives. Open to suggestions and corrections in the comments. Any italicized, all caps notes are meta commentary and invite conversation in the comments. Currently version 1.1] Intro When communities come together, especially when those communities are decentralized, it can be …

[LB]

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.

[LB]

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 ?

[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.