Creating Documentation on GitHub, review culture

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?

I’m perusing around GitHub, and they are exposing a “contributing” page that links to good first issues, contributing guides, and they claim it also uses machine learning to customize content. Here is an example for one of our repos:

and the article:

This is pretty neat, it’s the first attempt at an integration driven by ML, they report to use the Argo framework, and

We also plan to add a mechanism for maintainers and triagers to approve or remove ML-based recommendations in their repositories. Finally, we plan on extending issue recommendations to offer personalized suggestions on next issues to tackle for anyone who has already made contributions to a project.

It’s pretty neat because something like this promises the customize the experience based on previous GitHub experience, possibly making it easier for new contributors, or just more fun!

1 Like

Wow that is surprisingly good.

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

I would bet their algorithm saw (based on the human provided labels for the training set) that writing documentation was often a “Good First Issue” since you have to do a little learning / testing of the codebase (and I’d tend to agree with that too). Then since it’s TF-IDF they probably found that “documentation” just had high frequency in these issues, and now pouf we have an incorrect label, haha.

RIP goodfirstissue.com

Hey folks, another request for review is ready! See this topic. Contribute however you are able and comfortable to do so. [docs] GitHub Getting Started Request for Review

Another request for review of the sourcecred/docs glossary (or the start of it!) [docs] Request for review: glossary

Request for review of the contributing.md! [docs] CONTRIBUTING.md