Centralized all development documentation

[matklad]

TL;DR: https://near.github.io/nearcore/

At the moment, the docs targeting developers of nearcore are spread out across many different locations:

• docs/ folder in the repo
• wiki: https://github.com/near/nearcore/wiki
• the other wiki: https://wiki.near.org/contribute/contribute-overview
• various "how near works" videos on youtube
• confluence

We want to centralize all that into a single place, such that it's easier to find docs, as well as to add them (you don't need to deliberate where to put stuff).

We discussed that a bit on zulip and on the all-hands.

We figured out we want the following features from our doc system:

• publicly accessible, everyone can read the docs
• publicly editable, everyone can edit docs
• comments, so that it's easy to engage with the docs without necessary editing them
• stored in the repo, so that we can give public attribution to folks contributing to docs
• stored in markdown, so that it's easy to edit in Emacs
• stored in wyswyg, so that it's easy to edit outside of Emacs
• drag'n'drop experience for media like images, videos, etc
• has table of contents and in general easy way to organize large volume of loosely connected stuff
• reasonable eye-candy in terms of CSS

We considered a bunch of options, and ended up choosing https://rust-lang.github.io/mdBook/, the same thing that rust ecosystem itself is using, eg here https://rustc-dev-guide.rust-lang.org.

It doesn't have wyswyg, but the edit button which opens GitHub editor is pretty slick. It also doesn't support drag'n'drop for images, but an OK workflow is to drag images into a special GitHub issue, and essentially use that as an image hosting platform. It doesn't have comments, which is unfortunate. On all other accounts, it is pretty great.

Here's the partial laundry list of things to do to finish transition:

• setup minimal github action and github pages for rendering (feat: scaffold for dev guide #7668)
• setup skeleton docs (doc: book skeloton #7675)
• move contents form repo's docs folder into book (doc: move the content from docs to book #7677)
• double check source layout, naming, urls
• move repo's wiki into the book, kill the wiki (doc: move wiki contents over to the book #7706)
• move and kill the other wiki (CONTRIBUTING.md is a source of truth for nearcore wiki#55)
• make sure that contributing md and such refer to the book
• move over contents from confluence (doc: start moving "how neard works" to docs #7824, doc: move GC docs over from confluence #7826, docs: move transaction routing from confluence #7850)
• kill private pages on confluence
• kill public pages on confnuence
• add "how to add new contents to mdbook" practice
• re-read all the docs, remove/rewrite obsolete & poorly written parts
• go through go links
• go through any extra content, like the other wiki, youtube and what not
• move "observability" stuff out of architeceture&style into a dedicated chapter Document observability principles #7806
• move "testing" stuff out of architercute into the testing chapter
• refresh codemap
• re-do image which starts architecture?
• image for the core data model (blocks, chunks, receipts, parts, etc)
• link media issues from somewhere Media 🖼️ #7821
• update "How neard works when it is synchronizing" in "how neard works", it's a bit obsolete

Potential future work:

• Setup rustdoc #7836
• Consider adding giscus (comment system) to our dev docs #7827
• sort out golings -- they currently are accessible only to Pagoda employees.
• setup mdBool linkcheck
• To the architecture, add a "what" page which thoroughly documents the kinds of data in our system -- blocks, chunks, parts, approvals, trasactions, receipts, shards, trie nodes, contracts, accounts, etc.

[akhi3030]

@matklad : I would like to volunteer to help out here. Please assign tasks to me that you think I can help with.