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