RFC: one mdBook to rule them all

[matklad]

In this PR, I want to draft how we could centralize all our dev docs in a single, publicly accessible and publicly editable location.

In this PR I want us to agree on:

• centralizing all dev docs in single location
• using mdBook as a specific medium for the documentation.

To this end I:

• fleshed out the landing page of the book. Does it make sense to you?
• moved over some existing md docs: style and architecture
• moved one doc from confluence: gc.

See the rendered version here: https://matklad.github.io/nearcore/

Note the edit button as well:

[akhi3030]

This is absolutely brilliant. I am in full support for moving full steam ahead on this.

[mm-near]

how did you upload the images?

[matklad]

This is absolutely brilliant. I am in full support for moving full steam ahead on this.

I don't think this is absolutely brilliant, there's certainly some drawbacks:

• no lightweight comments
• no wiswig
• media management is worse than just drag'n'dropping images.

how did you upload the images?

Yeah, this is an important bit. For .svg illustrations, I put them in the media folder. I think we probably should try to stick to .svg as possible.

For .png illustrations, it would be possble to put them in media, but I'd rather not. I think it's important to try to keep repo size reasonable. So I use my standard trick here: host images on github: matklad#2

And yeah, this is the policy I'd love to propose:

• default to .svg
• if there's a need to embed something more binary, host it "elsewhere", where the default "elsewhere" is a "media" issue in this repo

[nagisa]

Worth noting that SVG isn’t always quite lightweight either. And unfortunately making modifications to an SVG will likely result in a non-trivial diff, unless the change is made by modifying the XML directly.

In the past for things like graphs I used mdbook-mermaid, and my belief is that this is the most appropriate way to make graphs actually editable and reviewable. I don’t think this is a requirement though.

---

Overall, I have had quite a good experience with mdbook personally, so 👍 from me on the general direction.

[bowenwang1996]

This is epic! I like the name of the branch :)

[bowenwang1996]

This document isn't publicly accessible right? Should we remove the link?

[matklad]

Yeah, we should do something here once we actually merge this stuff, I choose not to think about this yet.

That being said, I suggest not worrying about leaving some links to private stuff:

• this should be low-effort-to-write kind of docs
• if link is broken for someone, they'll bug us

[matklad]

Chatted with marcin about images, the current solution is OK. So, I consider the RFC accepted and would move to implementation work, which is tracked at #7670