docs - comprehensive restructure/reorganization

[nickfrosty]

Problem

The Solana docs are difficult to navigate for people to effectively and efficiently locate the information they need for working with Solana. A comprehensive restructure/reorganization of these docs is in order to correct this issue.

Due to the large nature of this restructure/reorganization, it will take time and multiple PRs. This issue will be used to track the various phases and progress to complete the chunks of work to accomplish the full reorg.

Rollout plan

NOTE: For simplicity, all the document's and their paths listed below are within the docs/src

Phase 1: "Learn" scaffold

The "Learn" section has the overall goal of being containing the high level information about Solana as a whole.

Scaffold the new dedicated Learn section with the following pages:

• "Introduction" section (to be located at learn/intro)

  • [ ] relocate introduction.md to learn/intro.md
  • [ ] relocate history/md to learn/history.md
  • [ ] update sidebar for these new document locations
  • [ ] create redirects for these documents to their new location

• "Basics" section (to be located at learn/basics)

  • [ ] relocate wallet-guide.md to learn/basics/wallets.md

• "Economics" section (to be located at learn/economics)

  • [ ] relocate economics_overview.md to learn/economics.md
  • [ ] remove storage_rent_economics.md
    • duplicated page; also contains outdated info on rent
    • see #29302
  • [ ] relocate transaction_fees.md to learn/economics/transaction_fees.md
  • [ ] relocate inflation/*.md to learn/economics/inflation/*.md
  • [ ] update sidebar for these new document locations
  • [ ] create redirects for these documents to their new location

Phase 2: Developer Guides

• create new "Developer Guides" section (located at developing/guides)
  • [ ] relocate the JS example guide from the Versioned Transactions page to here
  • [ ] relocate the JS example guide from the Address Lookup Table page to here
• relocate the getstarted/*.md guides to here
• relocate the "quickstart" section of developing/clients/javascript-api.md to a new separate developer guide

Phase 3: Core concepts

The most of the various "core concepts" pages reside within the current developers section of the docs, even though this information is relative to all users of Solana, not just developers.

Most of these types of pages will be relocated into the Learn section, including: transactions, accounts, programs, CPI, clusters, staking.

Phase X: Architecture

The architecture section has a goal of going deep into the various internal portions and mechanisms for Solana. The goal is to also add more useful and specific content within this section, but not necessarily as part of this restructure.

Phase X: Developers

The one-stop-shop that developers cane use to onboard into Solana development. Including "getting started" guides, local development, various developer resources, etc.

Phase X: Validators

Home to all the info needed to effectively run and maintain a validator. This may result in a restructure of the current Validator pages including merging in the pages from the Validator Guidebook.

TDB relocations/reorganizations

The following documents are earmarked for reorganization within the docs. They are listed here for simple tracking until their specific location and/or "phase" is determined:

• relocate the wallet-guide/*.md files to within the cli directory (all these documents pertain to specific usage of the CLI for the various types of wallet, e.g. paper, file system, hardware, etc)
• potentially relocate the exchange pages
• duplicated content within the transaction_fees.md and developing/intro/transaction_fees.md files
  • smartly merge these documents together
• the staking.md and staking/stake-accounts.md documents
• proposals may be relocated out of the monorepo, (if/when they are, the exact location is yet to be determined)

[mvines]

This is exciting. Generally I'd like to the scope of the monorepo docs reduced significantly. All content that is not specific to the Solana Labs validator client and related command-line tools belongs elsewhere!

[nickfrosty]

@mvines I would think that may also result in ultimately removing the developers sections as well. Is that you intention?

[mvines]

Yeah definitely.

[nickfrosty]

So then you envision the mono repo docs only having these sections (based on the current contents): cli, validator, and potentially architecture (I'm guessing this section could go either way since the architecture would be the same for all validator clients, but also being covered by the new spec repo?)

[mvines]

Exactly. Architecture of the Labs validator client certainly belongs in the monorepo docs, but architecture of Solana as a whole certainly not.

This is just my general vision though, as far as I know there's nobody that's currently taking steps to make it happen :)