Proposal: A new structure of the documentation

[novusnota]

Core ideas

1. Documentation should start being helpful as quick as possible (A brief "Getting Started" should be the part of the main/index page)
2. Documentation should differ between advanced and novice users of Tact and TON Blockchain (as mentioned in "Coming from FunC" page tact#1130):

📛 Criticisms of the current structure

Language/Guides section is getting too big to not have it's own dedicated section

Moreover, its scope is wider than the language itself, as it includes interaction with Tact's tooling and TON Blockchain concepts applied with respect to FunC's idioms and their compatibility with Tact.

Besides, the current naming is more of a misnomer, as it usually means deep articles describing how to make a specific project, while the current ones are more descriptive of the language and, only partly, of it's applications in real-life contracts. This is similar to online documentations other languages have, where they call them Books of the language (See Rust's documentation book). I suppose it would be nice to call our section Book as well. Alternatively, it can be named "Learn".

It's only natural to put #66 there :)

P.S.: All the actual guides and tutorials from people all around TON Blockchain would be referenced in the Ecosystem section covered below.

Getting Started is too slow (/start)

People, first coming to the docs should see:

1. Basic overview of it's parts
2. Very brief and very quick "Getting Started" page, telling them how to deploy their first contract and where to look for further information after this. The page shall not go into details and describe, say, receivers like the current /start does.

And instead, currently people see some mediocre looking README-like page. Yes, it has some of the important links, but the rest isn't suited for the awesome Tact documentation I'd like to see :)

Information from the current "Getting Started" page should be moved into relevant sections of a new Book section described above.

Current grammar page is useless (/language/guides/grammar)

tact-lang/tact#1173

Evolution section's scope is too narrow (/evolution)

And despite that, it still occupies the whole section of the docs! On top of that, the current changelog page (/language/guides/changelog) is out of date and doesn't keep up with latest Tact updates as described in #77.

Tools section's scope is too narrow (/tools)

Instead, it should become a part of a much broader section, Ecosystem, which would cover "what's out there" with more detail than just quick links. This would include the current Tools section and make many detailed references to great content posted to tact-lang/awesome-tact.

✅ Proposed solution

Broad ideas

Main page of the docs should have a quick overview of available things and a very short getting started guide for deploying the very first contract as quick as possible.

Three sections, each having an index page describing available contents. Their position indicates the levels of immersion into Tact and TON Blockchain, going from the very shallow on the "left" (main page) to the very deep and very broad on the "right" (ecosystem section):

1. Book (or Learn) — intended for those having surface-level (or no) knowledge of Tact and TON, or for those familiar with other blockchains (#54, Docs: "Coming from Solidity" page tact#1170).
2. Language — for people wanting to go deeper, and those (already) familiar with TON. More of a detailed reference, then a manual.
3. Ecosystem — for people wanting to go broader and, perhaps, contribute to the ecosystem.

New structure

• / — main page of the docs. Very important!

• / book (or /learn) — section (and a dedicated page) for learning all things Tact and some things TON. Because there's an awesome docs.ton.org resource, many articles and guides, we should reference as much of it as possible, while still remaining Tact-specific and novice-friendly.

• /language — section (and a dedicated page) for the vast overview of the language, including:

  • /grammar — a dedicated grammar page, Docs: complete annotated grammar reference/spec from grammar.ohm tact#1173
  • /ref — no change
  • /libs — no change
  • /evolution — current /evolution section should move here, plus a Changelog page (current one has to be replaced by a link to tact-lang/tact/CHANGELOG.md as per tact-doc's changelog is out of sync with tact-lang/tact's changelog #77)

• /ecosystem — section (and a dedicated page).

[novusnota]

@anton-trunov @Gusarich what do you guys think?

[anton-trunov]

Sounds just fabulous!