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 @vsoch 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

For GitHub docs, and especially those around community (code of conduct, contributing) is there any reason to not take advantage of a repository called .github? Here is a little background - https://help.github.com/en/github/building-a-strong-community/creating-a-default-community-health-file the basic idea is that you can put these common community files there, and then in any organization repository that doesn’t have it’s own version (either in a .github folder or just at the root) it will “discover” the organizational repository.

My thinking is that we either scrap that GitHub helper and just put all docs in the current proposed location (and users will discover by way of links, web interfaces, etc.) or we decide that there is some fundamental difference between a set of “official community docs” (the ones expected and listed by GitHub in the link) and then have two repos, and then just use standard JavaScript to pipe the content into the same web interface. Thoughts?

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

Correct! The way I understand it, we could have a general code of conduct or contributing.md, and then a local repository can easily override it.

It’s a pretty silly suggestion (but I’ve used it elsewhere) - every GitHub file has a raw url, and so we would do an Ajax/fetch (or similar) request the page, and then a markdown to html library to render and add to some element on the page. That way, the most updated version of a document (on master branch in the .github repository for example) is always rendered in the web interface (for the docs repository) without anyone needing to do manual updates. Yuck, let’s avoid manually updating more than one document!

  • Agree on the first point, we use docs repo for community review, and then serve specific files from a .github repository.
  • For discoverability, I believe that GitHub will automatically provide a link to code of conduct / contributing / community files when a user makes their first contribution, for example. We would want to enhance that with links on sourcecred.io and the docs site - nothing should ever be hard to find. For example, on the page that renders the Code of Conduct or similar, there should be an “edit me” button that takes you right to giving feedback on the file in GitHub.

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)?

Yes, 100%. Here is a site (that is deprecated but still up) that loads a list of contributors from a markdown file - http://singularity.lbl.gov/people it’s hosted on GitHub pages (static!) and (amazingly) still hasn’t been taken down :slight_smile:

And here is a slightly more attractive, but still simple, example of rendering a markdown file (the pledge) into the page. It’s just a get request. https://good-labs.github.io/greater-good-affirmation/participate/.

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:

A few more comments from the dinosaur gallery! (I took my cocoa break and read more carefully and now there is more content coming out of my fingers, haha).

  • Theme: Given that we are using GitHub, I hugely advocate not just for GitHub pages, but for using Jekyll, which renders natively there. We would not need to set up a custom build to use another static site generator (e.g., mkdocs) or something like hugo. We can remove that step entirely and have the master branch (or docs folder) render natively. If there is a template that you like in some other language, then I can offer to convert it into Jekyll (I do this regularly just for fun, a few examples are here with mkdocs, docsy (hugo) and an sb admin theme) https://stanford-rc.github.io/rse-services/docs/resources/documentation.
  • .github repository - I’d like to volunteer to take charge on putting some early content together for this - if the repository is created, I can open issues to get feedback from the community about templates we can start from, and then I can open the first PR with an actual suggestion.

Also something else that just came to mind - if we use GitHub, there is a funding.yml file that is becoming standardized, and can render into a sponsors button. How would sourcecred fit into this landscape? For example, let’s say we add that button to our repos, and then someone contributed something. Would it be converted to cred? Would / could cred be an actual unit of sponsorship, meaning that someone would actually add it to their funding.yml?

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

https://vsoch.github.io//2019/transparency/

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 @vsoch

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.

@vsoch, are you interested in championing?

Yes! Actually I just created a repository and wrote up a proposed plan, check it out here Proposal for Community Health Files.

[edited] copy paste fail, haven’t put in my contact lenses yet. Probably should take a break and properly do that :stuck_out_tongue:

1 Like

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.

Huh, I was thinking about it the other way around (.github renders in docs) but re-thinking this, I’m +1 too to have docs --> .github. It’s definitely feasible with GitHub actions to keep the two in sync, and definitely less confusing to have one central place for docs.

1 Like

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.

@vsoch, 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.)

@vsoch 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).

We have another request for review! See this topic for details on the Code of Conduct.

@s_ben sorry I’m just seeing your comment now as I’m closing the tab! I could write an initiative if it’s a hard requirement, but I don’t care about the cred part enough to do it just for that. I’d rather GSD - get “stuff” done, haha (insert another word there that I shouldn’t post here! :wink:). I’m happy to do it if it’s official or required, but it does feel like extra work, and maybe I can do okay just being loud in various places about getting feedback when it’s needed for each document. What do you think?