Creating Documentation on GitHub, review culture

Per the thread on review culture (and associated pull request on the new /docs repo), we have reached rough consensus on a review process for important documents and associated “review culture” around that. More to come, but essentially it is applying best practices around contributing code in OSS projects to documentation. Below, I outline my initial thoughts on how we can realize this process, list the documents that need creating, and offer some best practices I’ve come across during my time in the technical documentation mines. If you have any critiques/ideas, let me know in the comments!

Phase I

We start creating docs in the new sourcecred/docs repo. The 1st pull request (PR) in the repo is a guide on review culture, which should be merged soon and become our first official doc in /docs. If contributors are new to GitHub, myself or one of the devs can jump in and help (it’s not so bad I promise!). Going through the process of submitting docs, reviewing them, reaching consensus and merging should be a good learning experience and help us refine the review culture doc. The social contract and community contract docs suggested by @anon60584824 are good candidates IMO, as they require input from the community at large, aren’t too technical, and would be good to have ready when new people come to the project. We could also do the glossary @Beanow suggested, or a user guide (if we don’t think it will change too much).

Contributors can also practice updating existing docs on GitHub should they wish, such as the README on sourcecred/sourcecred (which is likely outdated).

At this point, those involved in these efforts will at least have a toehold in the GitHub graph, getting some of that sweet GitHub cred. And they will know better if they want to step up and champion docs Initiatives going forward, perhaps have better ideas for how they should be structured.

Phase II

Once we’re all familiar with GitHub and have created a couple docs, we create a proper Initiative (or Artifact?), as outlined in the Beta Roadmap. This will allow us to scope out tasks and assign champions. The main tasks I imagine are:

  1. Decide on how we want to structure docs in the repo, what tools and platforms we want to use. The typical way an OSS project (and most startups) do this is with a separate docs website. Typically a static website generated automatically from MarkDown files stored in GitHub. As an example, here’s the docs site I work on in Decred:

https://docs.decred.org/

Here is the repo those docs are stored in:

If you look through the Issues and Pull Requests (PRs), it will look much like the process outlined in the review culture doc.

Another alternative is to just leave the docs in GitHub. This is less fancy, but works fine, especially early on when other projects don’t expect a lot of polish. If we want to get experimental, we can explore user-editable wikis and other less common doc strategies that may fit well with graph-based valuations.

  1. Create key documents. Below are a list of docs that I could see going in /docs.
  • Basic technical documentation for installing and running SourceCred. For now that’s just the README on sourcecred/sourcecred. We can probably just do minor updates here for now. But if we create separate docs, they’ll probably live in /docs.

  • Social contract

  • Community contract

  • Official user guides. E.g. guides on Initiatives, Artifacts, a “qickstart” guide to get someone up and running in 5 minutes and excited, etc.

  • Glossary

  • (Future) user guides. When we have a dedicated UI to play with, we’ll need guides showing people how to Boost, navigate the graph, etc.

Phase III

Revel in the glory of docs cred, come up with new Initiatives.

3 Likes

Was not aware of the community health docs feature. This makes a lot of sense actually for the ‘social contract’ and ‘community contract’ docs. Those should be applicable across all repos in the /sourcecred org.

It’s possible the CONTRIBUTING.md file could change per repo. For instance, different repos have different technical requirements or maintainer-created norms for contributing. I know we’re trying to standardize, but as the project grows I imagine maintainers will develop strong, perhaps valid reasons for doing things a little differently in their repo. But it looks like a maintainer can override the default CONTRIBUTING.md file simply by putting one there themselves.

I’m not sure I understand the technicals here…but the general requirements I think make sense:

  • There is a mechanism for the community to review (using our review culture) docs that are widely applicable in the project. Using a /docs repo for that makes sense. Even if the repo is only used for reaching consensus, and the COMMUNITY_CONTRACT.md file, for instance, lives elsewhere (and is automatically served to other repos in the org).
  • Docs are discoverable. I think there’s a fairly strong norm (at least in OSS communities) to look for a CONTRIBUTING.md or /docs folder for guidance on contributing. But we want SC to be accessible to non-tech user cases too, some of which will use GitHub to collaborate. You mention discovery by links, web interfaces, etc. It would be good, for instance, to be able to discover this stuff from https://sourcecred.io/, which will be the initial entry point for many.
  • Docs are maintainable. The .github repo sounds good in this respect, as it automatically propagates the files to other repos. We want to avoid a situation where the same doc lives in multiple places. This often leads to some copies drifting out of date…

Not a silly suggestion! I’m always hesitant to add things that are brittle and create maintenance work, but GitHub URLs, MarkDown and html rendering I can’t imagine changing anytime soon. Serving those files up dynamically could be a good way to keep docs in sync after updating them. One question I suppose is, would this work with static websites (the method de juor these days)?

This all looks like a good plan to me…Will see if anyone wants to chime in with other ideas, but if there are no objections I say let’s use this :+1:

+1 Jekyll. Have used that in past projects and had a good experience with it. Always used a custom build process, so it’s cool that we don’t need that. It will lower the barrier to contributing.

Makes sense to me. Perhaps this is an Initiative you can champion? I’m still a bit confused honestly as to how Initiatives work, but we should reward this in the graph somehow.

It’s funny, this made me think of a podcast I listened to recently on the importance of being transparent about OSS funding. Looked it up and it was your podcast! I think I found this when I was checking out your Twitter or something when you joined. But it’s been rattling around the back of my head when I think about these issues.

It’s a good listen, and you make some good points. Contributors should have visibility into who is funding a project (or know that the donors chose to remain anonymous (which will happen too)), in order to make an informed decision and not be blindsided by ickiness. I know we shout out @protocol as a funder of the project in multiple places.

Not sure how someone donating via sponsor button would make it into the graph…I think the idea is that we want people injecting money/value through Boosting, playing the SourceCred game (and increasing the utility/value of Grain). But how does that get surfaced? How do we reward people that contribute through outside channels. This is an open problem we’re still grappling with. But I digress…we should probably create a new post on transparency so as not to divert this convo (and more cred :innocent:)

Great ideas @anon60584824

I imagine docs will have a broad application, like the glossary, official technical overview and guides maybe, so applying a theme and hosting as a static site makes a lot of sense to me. I’m assuming we would link to this from the homepage (or make it the homepage), Discourse and Discord too.

So the .github repo is pretty neat, perhaps we can track the files we want in there from docs. So COMMUNITY_CONTRACT.md and the likes could be maintained there, making them available in the rendered site too as a canonical doc. Perhaps using automation to copy these into the .github repo?


In terms of phases and goals for the documentation, I think using this process to settle on and write down shared community values is proving to be really valuable already :] so I would like to keep that effort going and dive into more topics like governance, social contract, code of conduct, and the likes.

The other big areas I’m hoping for is to make it a good entry point for people who are new to the project. And to have a shared language to base discussion around.

In my opinion having easy to read, brief, coherent and low-noise official docs for this would be ideal :]

Bandwidth is something I’m definitely concerned about though. So my intuition would be to start small. A one-paragraph summary + link to a forum thread, for a variety of topics. Supervised by a docs Champion who prioritizes the easy to read aspect and takes ownership of the overall structure. That would be my suggested first milestone.

Though I’m open to other ideas and approaches, I don’t believe I’ll be able to fill said Champion role as I have a few others to look after :smile:

Agree with this. I think we have the technical chops and enough consensus already to bang something out fairly quickly, start iterating.

@anon60584824, are you interested in championing?

Excited to see the discussion here! I’d like to +1 keeping sourcecred/docs as the source of truth for all our official docs (way less confusing for the community) and then treating the sourcecred/.github repo as an implementation detail–ideally with some automated tooling to ensure that the files we are mirroring from sourcecred/docs into sourcecred/.github automatically stay up to date.

The way I was interpreting what @Beanow said was, “let’s create the docs in /docs (which will require some convo/rounds of edits), and have the files live there, as people will naturally look in /dcos for documents”. Which is what I think we should do for discoverability in any case.

@anon60584824, do you want to go ahead and create a an Initiative with yourself as champion? This is still how we’re still doing it right @Beanow? I’m imagining Proposal for Community Health Files is a good scope for an Initiative, as there are a number of other doc projects people could nominate themselves for under the umbrella of documentation (e.g. glossary, how-to guides, etc.).

Yes, I think an Initiative for this makes sense :smiley: If you like, you can write an Initiative in the same way the others are currently written. As a forum topic using the provided template. Or a “Cred historian” may take up that role for you in retrospect.

(Don’t worry about planned changes to Initiatives for now. The format is very similar, so we’ll port it when the time comes, and we will still want to have forum topics as a place for discussing them. Plus going through the effort of filling out the template and documenting Initiatives is very helpful in and of itself.)

@anon60584824 are you up for writing an Initiative for this? That way you presumably get cred earlier (and more definitively) vs. waiting on a cred historian to do it later (not sure the timeline for when that starts happening).

Wow that is surprisingly good.

Some difficult ones in there, like Document the core architecture :sweat_smile: But overall lot’s of good suggestions.

RIP goodfirstissue.com