Reviewing Docs PRs (very low risk)

My personal view is that there are high risk PRs (consensus code), medium risk PRs (non consensus code, GUI?), low risk PRs (tests) and very low risk PRs (docs) in terms of introducing bugs, vulnerabilities and so a review process that makes sense for consensus code doesn't make much sense for docs.

We should encourage use of simple ACKs and NACKs (Concept ACK, Approach ACK don't make much sense in a doc scenario) and doc nits can generally be addressed in a follow up PR if the nit commenter cares that much about the nit.

Docs and certainly nits should not take up valuable review time from long term contributors and maintainers.

We certainly don't want inaccuracies or poor quality docs introduced to the Core repo. So an ACK/NACK review is still important. And if a reviewer feels strongly enough that a certain doc PR is a deterioration we absolutely need a NACK. But we also want to avoid circles of conflicting nits because reviewers feel that they need to review in the same meticulous way as they review consensus code. I observe people generally want to add nits rather than a simple ACK because it feels as if they are being helpful.

The various sources of Bitcoin Core developer documentation

• bitcoin/bitcoin/doc is the primary place for completed developer documentation. I propose creating a /developer directory here. The developer notes is very long now and should in my opinion be split up into separate docs within this new /developer directory. (NACKed)

• bitcoin-core/bitcoin-devwiki is used for drafting and general adhoc stuff that doesn't fit anywhere else. This is not a general documentation resource. Once something is finalized here it should be brought into this repo bitcoin/bitcoin/doc.

• bitcoin-core/docs is only used for Gitian build files currently. This is not a general documentation resource.

• btcinformation.org (@harding and @achow101 are contributors) contain external developer resources that can be linked to if/when required. When developer documentation doesn't fit into bitcoin/bitcoin/doc a good alternative is there.

• bitcoincore.org was historically used as an information source for certain topics (RBF and SegWit). However, today it is just used to provide binaries of Core releases, release notes and isn't used to provide additional information.

• Bitcoin StackExchange is a good place for asking questions that you don't think are answered in the primary docs. After receiving an answer there please consider opening a PR to improve the docs in this repo.

I don't think we should be afraid of introducing concepts and links to other resources, related PRs, related PR review club sessions, transcripts of relevant presentations in docs like multiprocess.md. For example, that doc hasn't been updated since July 2019 (no criticism intended but this may be due to docs being lesser priority, the headache of nit reviews, or merely the confusion of which location certain information should go.)

Policy on linking to external URLs from docs

Ideally we only want to link to resources that will still be there in 5-10 years. Bitcoin StackExchange, @kanzure transcript site, PRs etc have stood test of time in terms of persistent links and I am confident that Bitcoin Core PR review club, Bitcoin Optech, Blockchain Commons will too.

If we start splitting up longer docs we can potentially draw in docs like some of @jonatack docs that I regularly direct people to rather than the Bitcoin Core docs. Or this blog post from @luke-jr on how to securely install Bitcoin Core. Or some of the related dev content on Stack Exchange such as this on multiprocess.

These are personal views and I welcome thoughts and feedback (NACKs welcome).