[docs] docs.gno.land overhaul

[zivkovicmilos]

EDIT Nov '24: See up-to-date issue #2953

---

Description

This issue outlines a proposal to improve the existing state of the gno.land documentation which:

• requires double work across 2 repos for propagating changes
• is constantly outdated, especially in the context of tools and tools usage
• lacks proper Reference documentation, especially for RPCs and important configurations
• contains documentation in sections that doesn't belong in those same sections
• ...

⚠️ The issue is constantly being updated with feedback, and will branch out into different sub-issues that can be tackled by the core team ⚠️

High level choices

• Drop gifs, embrace vhs (cc @gfanton @ajnavarro for solving the storage issue). Generate gifs on build, with the monorepo docs having only the tape files
• Move out the JS client docs (tm2-js-client and gno-js-client) into their own respective documentations (not on the gno official docs). We utilize JSDOC for the source code anyways, so the docs generation should be straightforward
• Drop the custom sidebars.js in Docusaurus, make sure it's autogenerated based on the docs file directory
• Separate the docs into 5 top-bar sections: Gno.land, GnoVM, Tools, Ecosystem, FAQ

High level structure

The high level structure for the documentation should be divided in 5 sections. All of these are discussed below in detail on their initial structure:

• Gno.land - contains documentation relating to the Gno.land blockchain / TM2
• GnoVM - contains documentation relating to Gno (the language) and the VM. This part of the docs should not be related to the blockchain aspect of the project
• Tools - contains documentation on the different tools and services we have running
• Ecosystem - contains documentation on the different implementation partners, GOR, the gno grants program and more
• FAQ - contains frequently asked questions, divided by different top-level categories

Gno.land (section)

The high-level overview of the Gno.land section can be represented through the following directory tree:

.
└── gno.land/
    ├── overview.md
    ├── getting-started/
    │   ├── gnodev.md
    │   └── gno-playground.md
    ├── how-to-guides/
    │   ├── how-to-write-a-simple-app.md
    │   ├── grcs/
    │   │   ├── how-to-write-a-grc20.md
    │   │   └── how-to-write-a-grc721.md
    │   └── infrastructure/
    │       ├── how-to-setup-local-chain.md
    │       └── how-to-connect-to-existing-chain.md
    ├── concepts/
    │   ├── realms.md
    │   ├── packages.md
    │   ├── effective-gno.md
    │   └── proof-of-contribution.md
    └── reference/
        ├── RPC.md
        ├── testnets.md
        ├── node-config.md
        └── stdlibs/
            ├── address.md
            ├── banker.md
            ├── coins.md
            ├── realm.md
            ├── events.md
            └── chain-related.md

The individual subdirectories and files contain previously present and new documents, making it easier to discover the gno.land blockchain.

Key changes:

• getting started modeled around gnodev + playground
  • This is the absolute beginner intro on getting started with gno.land as quickly as possible
• how-to guides simplified, condensed
• concepts simplified
• RPC reference that is interactive and callable, through the OpenRPC specification

GnoVM (section)

The high-level overview of the GnoVM section can be represented through the following directory tree:

.
└── gnovm/
    ├── overview.md
    ├── architecture.md
    ├── lifecycle.md
    ├── storage.md
    ├── *.md
    ├── gnolang/
    │   ├── go-gno-compatibility.md
    │   └── *.md
    └── specs/
        ├── gip-01.md
        └── *.md

This structure is just an example of the GnoVM section, but the highlight is that we want to separate out the Gno / GnoVM documentation from the blockchain aspect of the project.

The purpose of this separation is to have clear docs if someone wants to focus more on the VM rather than the blockchain.

Tools (section)

The high-level overview of the Tools section can be represented through the following directory tree:

.
└── tools/
    ├── overview.md
    ├── gno/
    │   ├── overview.md
    │   ├── how-to-build-run.md
    │   └── how-to-do-*.md
    ├── gnokey/
    │   ├── overview.md
    │   ├── how-to-build-run.md
    │   └── how-to-do-*.md
    ├── gnodev/
    │   ├── overview.md
    │   ├── how-to-build-run.md
    │   └── how-to-do-*.md
    ├── gnofaucet/
    │   ├── overview.md
    │   ├── how-to-build-run.md
    │   └── how-to-do-*.md
    ├── tx-indexer/
    │   ├── overview.md
    │   ├── how-to-build-run.md
    │   └── how-to-do-*.md
    ├── tx-archive/
    │   ├── overview.md
    │   ├── how-to-build-run.md
    │   └── how-to-do-*.md
    ├── supernova/
    │   ├── overview.md
    │   ├── how-to-build-run.md
    │   └── how-to-do-*.md
    └── gnobro/
        ├── overview.md
        ├── how-to-build-run.md
        └── how-to-do-*.md

Each tool will get its dedicated subfolder, with 3 main components:

• overview on what the tool is, what problem does it solve
• how to build / orchestrate the tool
• how to do X with the tool (how-to guides for using the tool)

Having the tooling documentation separate eliminates the need of having tool docs in the How-to section of the main Gno.land docs.

Ecosystem (section)

The high-level overview of the Tools section can be represented through the following directory tree:

.
└── ecosystem/
    ├── game-of-realms/
    │   ├── overview.md
    │   └── *.md
    ├── grants-program/
    │   ├── overview.md
    │   └── *.md
    ├── workshops/
    │   └── *.md
    ├── presentations/
    │   └── *.md
    └── contributors/
        ├── onbloc/
        │   └── *.md
        ├── berty/
        │   └── *.md
        ├── teritori/
        │   └── *.md
        ├── dragos/
        │   └── *.md
        ├── poc-students/
        │   └── *.md
        └── zone-011/
            └── *.md

The highlight of the Ecosystem section is the different contributor-facing initiatives we have with the Gno community, as well as showcasing the top contribution partners.

FAQ (section)

The high-level overview of the FAQ section can be represented through the following directory tree:

.
└── faq/
    ├── game-of-realms.md
    ├── validators.md
    ├── grants.md
    ├── gnovm.md
    ├── gnoland.md
    └── *.md

The idea behind the FAQ section is to have curated commonly asked questions for different categories, such as validator running, GOR, the grant program, and others.

Implementing this proposal

• Drop dependency on a custom sidebars.js, reorganize the docs folder according to this structure
• Fill in missing docs, condense existing ones according to the section structure
• Add support for vhs tapes
• Add workflows for having deployment / build previews (on the gno monorepo)
• Add support for interactive OpenRPCs on the RPC reference page
• Deploy the JSDOC docs for tm2-js-client and gno-js-client

[Kouteki]

I really like the overall approach and the structure. It offers both handholding for new people looking for tutorials, and reference type help for experienced community members looking for specific info. Minor nitpicks:

• Getting Started should have more substance, and cover more than just the setup. E.g. how-to-write-a-simple-app.md makes more sense to be here. But we can figure that one out later, and possibly even source the Getting Started content from the community.
• FAQ (section) / The high-level overview of the Tools section.. a typo :)

[thehowl]

Thank you for putting into question the organization of the docs. I've long thought it was misguided but I didn't want to catch up to the discussions of why the current "framework" was chosen.

Drop the custom sidebars.js in Docusaurus, make sure it's autogenerated based on the docs file directory

Yes please, and drop the front matter with the ID. The file name should be enough. Documentation on the repository should be renderer-agnostic. (I'm OK with "callout" syntax; these can be implemented elsewhere, but let's not add other docusaurus-specific things).

---

Things I dislike about the structure:

• non-monorepo and contribs/ tools shouldn't get their page on the documentation, except maybe for gnodev. We should have their documentation on GitHub.
  • They should be autonomous in their documentation. Restrict the scope of the docs, don't expand it. We should focus on doing a few very good and detailed pages.
• This goes also for the "Ecosystem" section. I don't get why it should exist here. If you want to have a "Showcase" page, then have it. But we shouldn't have information on Onbloc/berty on docs.gno.land, or have information like for GoR/Bounties here. These are not docs.
• FAQs should be a single page in the "Getting started" question. Specific pages can have FAQs when they are specific (ie. it's OK to have a FAQ section in how to set up a validator node)

Here's an alternative idea on the structure

• Getting Started (we need a place that screams CLICK HERE for beginners)
  • Install gno + gnokey + gnodev
  • Tutorials
  • Gno by Example (third party link)
  • Glossary
    • I'm thinking something like this document I made for the challenge series, specifically the "terminology and concepts" section. I want a page where all the buzzwords about Gno, blockchains and possibly also go programming are explained in a way that is simple and to the point. We need a way for non-blockchainers to not get lost.
  • Talks
    • Maybe just a link to gnolang/workshops.
  • FAQ
    • We should have a single page which gives straight answers and points to other pages to learn more. I like FairEmail's FAQ, because it really has most of the questions I had about the software, and they could be simply CTRL-F'd.
• Gno (Gno.land serves the creation of Gno's ecosystem and its further spread; Gno is a higher priority concept to talk about.)
  • Effective Gno
  • Feature Reference / Go-Gno compatibility (ie. features on top of Go)
  • Developing Gno (using in editors, playground, running + testing cycle)
  • Tools
    • Linter: gno lint
    • Docs: gno doc
    • REPL: gno repl
    • Debugger: gno run -debug
  • More specs and architectural documents in the future, like the ones you mentioned; but they take a shitton of time to write, so let's go with what's most important for the user for now and is already clearly well-defined for public consumption
  • Standard Libraries
    • Reference to web package documentation once it exists. (We can keep the std docs for now, but they are not autogenerated so they fall out of sync).
• Gno.land - yours is mostly OK, I'm just going to comment on what I think should be changed:
  • Stdlibs shouldn't be here
  • RPC should be lowercase (likely just a typo, but just to be sure - all filenames lowercase)
  • "How to grc" and "how to simple app" guides should go in "Getting Started" or in Gno by example. Otherwise, in "Getting started".
  • Gnodev should have a reference page on how to use it, not a getting started guide
  • There should be more info on the config, docker-compose configuration, ...

Things to note:

• Specs shouldn't be sequentially numbered. Proposals should be. It is the case that in many ecosystems these are the roughly the same (like ERC, BIP, RFC (IETF), or PEP (Python)); however I believe the documentation should talk about how things are without having proposals "frozen in time" where some of the information may be updated.
  • I'm tempted to suggest GRPC (Gno Requête Pour Commentaire) as a name for Gno's proposals, just to piss Jae off.

We need talks on the homepage. I'd say three, off the top of my head this could be a good set:

• Jae's talk at Gophercon
• Dylan's workshop at Gophercon
• something more on the blockchain side (like maybe Stanford, or Denver)

[zivkovicmilos]

@thehowl
Thank you for the writeup, I have a couple of concerns with the suggestions:

non-monorepo and contribs/ tools shouldn't get their page on the documentation, except maybe for gnodev. We should have their documentation on GitHub.

Do you envision the tool docs to live in the monorepo, alongside the tools?
How would users search for it, by going to the source directly and checking if there is a README?

I feel like this is what the docs are for, and we should use the already present docs indexing feature that serves up this documentation, since all of these listed are official tools we have and use daily

This goes also for the "Ecosystem" section. I don't get why it should exist here. If you want to have a "Showcase" page, then have it. But we shouldn't have information on Onbloc/berty on docs.gno.land, or have information like for GoR/Bounties here. These are not docs.

This section was merely a suggestion to get thoughts -- I think at some point we should actually have info for GoR / Boutines on the official documentation, at least as guidelines. cc @michelleellen

FAQs should be a single page in the "Getting started" question. Specific pages can have FAQs when they are specific (ie. it's OK to have a FAQ section in how to set up a validator node)

I like this, instead of having a separate page with categories, we distribute the FAQs out into different sections ✅

• Gno (Gno.land serves the creation of Gno's ecosystem and its further spread; Gno is a higher priority concept to talk about.)
  • Effective Gno
  • Feature Reference / Go-Gno compatibility (ie. features on top of Go)
  • Developing Gno (using in editors, playground, running + testing cycle)
  • Tools
    • Linter: gno lint
    • Docs: gno doc
    • REPL: gno repl
    • Debugger: gno run -debug
  • More specs and architectural documents in the future, like the ones you mentioned; but they take a shitton of time to write, so let's go with what's most important for the user for now and is already clearly well-defined for public consumption
  • Standard Libraries
    • Reference to web package documentation once it exists. (We can keep the std docs for now, but they are not autogenerated so they fall out of sync).

Do you propose we rename GnoVM -> Gno?

I like this proposal, but I would also like to have documentation on the VM in this section. I think this is the part of the docs that we lack the most

Stdlibs shouldn't be here

Where do you suggest we shove them, since they are reference documentation?

Gnodev should have a reference page on how to use it, not a getting started guide

The idea is to integrate gnodev as the number 1 intro tool for newcomers, and ease them in into local node development later, this is why it's the focus for the Getting Started section. It's gonna have its own tooling documentation for advanced use-cases

There should be more info on the config, docker-compose configuration, ...

This is already mentioned in the references, config.md
For orchestration, we would cover that in the How-to guides for infrastructure, as well as in the tooling section for the gnoland binary

We can put the talk / workshop links on the "homepage" (main overview page) of the docs 👍

[thehowl]

Do you envision the tool docs to live in the monorepo, alongside the tools?
How would users search for it, by going to the source directly and checking if there is a README?

We can have links from the docs; ie. a "community tools" page. (Maybe this should be awesome-gno; but anyway).

The question here is what is the "notability" required for being in the documentation. For me, it should be the critical components of Gno + Gno.land, and gnodev just because it's so useful for realm development we have it as a tool in the base make install.

Having "low" notability requirements means that:

• our attention in making a coherent and high-quality documentation is scattered on more pages; creating more quantity than quality
• the attention of the documentation's user is scattered on more documentation pages, that are at least now not important to everyone developing on gno or launching a validator.

I believe we should strive to make a high-quality documentation with a narrow set of pages which are well-curated and filled with good information, and see how we can manage to keep them that way with time. Then, if we can find ways to add more external tools, to the same level of quality of the rest of the documentation and in a way that doesn't "distract" or "overwhelm" readers we should go for it. But I think we should work on a small, high-quality documentation now rather than a lot of pages which show no more useful information than what you can get with <command> --help.

As for search, as long as we communicate the scope of what we cover in the documentation and the tools cover their documentation all on the README (I don't think any of tx-indexer, tx-archive, supernova, gnobro needs more than that documentation-wise) I think it's OK. I may be wrong; but by my own experience, the only documentation where I do use the built-in search functionality is the mdn; often because I know what I'm looking for (like the HTML tag or CSS rule), I just forgot its syntax. Everything else, I just use normal search engines simply because they're better at "understanding" queries and ranking results than a built-in search like Algolia or MeiliSearch anyway. So I don't see it as a big loss; but I may be biased by my experience.

I like this, instead of having a separate page with categories, we distribute the FAQs out into different sections ✅

Note: I still think we should have most FAQs (anything regarding gnokey, gnodev, common errors, etc.) on a single page; just spreading out the ones that concern a specific usecase.

Do you propose we rename GnoVM -> Gno?

Yes, same as you have the Go documentation, not the gc documentation :)

And of course it should have VM information; but communicating how the language is different and how to use it is more important than the underlying details

Where do you suggest we shove them, since they are reference documentation?

#522 - basically, they should be generated the same way as pkg.go.dev. If they're not generated, they will fall out of date within a week.

How to do this for p/ packages is a no-brainer; https://gno.land/p/demo/avl should just give you the docs for avl. I think for stdlibs, it's likely to be https://gno.land/pkg/std or /doc/std.

[michelleellen]

Hi both,

• I am hoping we can have the ecosystem realm updated and host ecosystem projects and realm, which might make more sense than in the docs? We could have a link in the resource section. Personally, I think we should have the gno example packages linked in a resource section too.
• The bounties and contribution CTA would also be good to have on gno.land - I am not sure we should have them in the Docs, is this common practice? Can also be linked in resources?
• I like the community tools and tutorials (hopefully awesome repo and gno.me) would be good under a resource section too.

[thehowl]

Just for context on closing this - based on the result of this discussion, here and off-line, we'll circle back to this with a new proposal on how to reorganize the documentation.

[thehowl]

Up-to-date issue: #2953