docs.gno.land revamp

[leohhhn]

Description

Below outlines the reasoning & plan, organizational and content-wise, for the upcoming gno.land docs revamp.

Why?

We're doing a revamp to clean up and refresh the docs, and change what we want to tell our users about gno.land.

One of the main reasons for this revamp is to focus the content of the docs to users who want to become proficient Gnomes: they need to learn how to use Gno & the tools that support it, such as gnokey, gno, gnodev & last but not least, gnoweb.

The intent is to shift focus away from advanced usecases, such as setting up a new chain, to simple, "how to get started", "how to build xyz with Gno" & "how to become a good gnome/contributor" flows. This primarily puts the reader of the docs in the role of a newcomer looking to use gno.land as a platform to build decentralized, open-source applications, join a community of like-minded developers & users, and become a good contributor to the gno.land project.

Below are general notes and expectations, tasks to complete, and a preliminary index of the new docs structure.

General notes

• Docs should be framework agnostic.
• We need to start work with a simple GitHub flow: one repo contains content + framework. Currently, the framework we have is docusaurus, but with plans to embed the docs into gnoweb down the line.
• The revamp should happen from a clean slate: cutting everything that is unclear, undefined, or old. We should be reusing what we can from the existing content.
• Use embedded playground whenever possible. The framework keeps the choice to render it as a codeblock or embedded playground.
• Move docs-linter to the repo containing content to check for broken links.
• Netlify previews for frameworks we support on every PR are a must-have.
• No gifs inside the docs, since they present challenging to maintain - they’re a nice-to-have.
• The less assets (jpg,png) we have, the better. ASCII diagrams are a more practical option: plaintext, framework agnostic, and easy to maintain and update.
• No -help output doc pages. Generally speaking, tool flags should be self-explanatory and understandable to people who know what they’re doing.
• Link to other resources whenever possible: we should utilize examples/, gnolang/workshops, Youtube more.
• Fix outdated content throughout our repos (ie examples/README.md, plan.md, philosophy.md, etc). See to archive/remove unused/deprecated example packages and realms. While these are not the "official docs", they do indeed pose as important reference content to new developers, thus the need to clean them up.
• Docs should teach the technical content, but also showcase the vision and mission of the project, and explain why gno.land is making design choices that it's making (ie the minimalistic approach with markdown & gnoweb, becoming a good contributor, etc.).

Content order & flow

Should be dictated by the content itself, as opposed to the framework dictating it (which is the current case with sidebars.js). Ordering will be managed by a docs/README.md masterfile which will contain the docs index. This index will be the content index with all files linked, so that the file paths can be checked for validity, as well as used for generating a sidebar/navigation for a frontend. For actually generating content order, we have two options (RFC):

1. Hacky way: utilize lexicographical ordering to order files only using filenames. This approach is used by the Go documentation already, and was proposed by @moul some time ago. By using numbers like on the below image, we leave "spots" for new files to come in, while keeping the ordering intact.
   
   With this approach we can use docusaurus' autogenerated sidebar, and we can do the same for gnoweb down the line.
2. Write a custom tool to parse the index into formats understandable by docusaurus, gnoweb, and other frameworks. Could become hard to maintain.

We can go with option 1 we write the custom tool.

Finally, we don't have to conform to the simple UX we have currently; we could have something like what the Solana docs did with the content organization.

Tooling & client docs

We need a centralized source of truth for how to use a specific tool in order to avoid having to maintain multiple docs files, which has led to outdated information many times in the past. Here's the proposal discussed before:

• gnoland, gnofaucet, tx-archive, etc. should have READMEs in the place their code lives, and a doc folder of their own if the README is too long or needs to be cut up into different pieces out. The README of the tool should provide an overview/index in this case. In both cases, this content is the primary source of truth for these tools, which we link to in the official docs. These tools mainly concern advanced users, who are not the primary target group of the docs.
• gnokey, gnodev, gno binaries, as the main tools the reader will be using, should have their separate guides in the docs, to which we can link to from their respective READMEs, still keeping one source of truth. If these tools change, we need a safe way to make sure that the docs are up to date. We can do this with proper codeowners setups & pinging docs owners for a review on PRs that modify the usage of these tools.
• Client reference documentation (gno-js, tm2-js, gnoclient) are to be autogenerated & hosted elsewhere (npm, pkg.gno.dev). Guides on how to use these can exist as part of the docs.

Initial structure proposal

Legend:

• * needs to be written mostly from scratch
• @ needs to be modified or rewritten from existing content
• e will use embedded playground

Getting Started

• Intro to blockchains @ (@thehowl's explainer for GCUS24)
• What is gno.land & Gno? Why build with it? *
• Exploring gno.land @ (intro to the gnoweb + Render() + md minimalist approach)
• Getting started with Gno - Counter example *e
• Developing locally
  • Setup & installation
  • gnokey - Creating a keypair
  • gno - Running & testing your code *e
  • gnodev - Running a local development node * (possibly combined with the item below)
  • Full development flow - intermediate Gno example (showcasing std, p/demo, r/demo, stdlibs...) *e
• Deploying to a gno.land network (gnokey & playground)@
• Interacting with gno.land - registering a namespace + calling for example r/demo/userbook (gnokey & connect)@
• Becoming a Gnome (contributor)* - explainer on the philosophy, contributing, possibly GovDAO membership, etc.

Developer Guides

• Using gnokey
  • 4 of the existing tutorials e (possibly not needed under a separate section)
• Using gnodev - Full feature showcase @
• Using gno - Gno unit tests (covering context manipulation, uassert & urequire,...) e@
• Gno examples (explainer/context page for the folder, suggested packages to check out) @
• Using Gno Coins (using the TM2 Banker) e@
• Creating a GRC20 token e@
• Creating a .... (GRC721, DAO, ...)
• Connecting a Go app to gno.land @
• Connecting a JS/TS app to gno.land * (when gnoweb isn't enough)
• Listening to Gno events off-chain * (tx-indexer guide, connected with the above item. for users who need more functionality than gnoweb can provide, or need the service for other reasons)

Concepts

• Realms*
• Pure Packages*
• Package paths*
• Namespaces @
• Tendermint2 overview*
• GnoVM overview*
• gno.land's consensus & GovDAO* (?)
• gno.land networks
• Portal Loop

Misc (needs better name or make into a no-name section)

• Glossary*
• FAQ@ (to combine multiple existing FAQs) - possibly also split by section.
• Effective Gno
• gnolang/workshops (link)
• awesome-gno (link)
• Links (events calendar, discord, telegram, youtube)

Reference

• Network config / Available networks
• Go-Gno compat @
• std reference @ (write godoc and generate md)
• Clients & Tools (links)
  • gnoclient
  • tm2-js
  • gno-js
  • gnoland
  • tx-indexer
  • tx-archive
  • tx-exports

Remarks

• The proposed structure above is a starting point, to which we can add/remove things. Specifically, we can think of multiple getting started flows, and display them to the user on the landing page depending on their profile/skillset (web3 dev, web2 dev, devops, etc.), as for example here. cc @thehowl - maybe we can have a full gopher getting started flow.
• Let's experiment with different UX flows; a sidebar is quite plain; maybe we can have something similar to the outlined Solana, Fuel or Tenderly docs. RFC.
• The FAQ and the Glossary should be packed with most if not all common terms and questions. This is the place I expect users to go to if they don't know where else to look. I invite everyone to start their own little note where you can jot down items for these and we can unify later. Another option is that I can open up issues here, and use that as the collaboration point to build these two resources.
• Apart from this proposal, I am preparing a learning flow for the Web3 Dev persona which will also serve as a reference.

I am taking the lead on this effort, however, this cannot be a one-man job; I need help from others, as discussed previously on multiple occasions. Below are some things to consider:

• The reference documentation for all tooling, GnoVM, TM2 is owned by the core team. Thus, docs for the tools, as outlined in the "Tooling & clients docs" section, should be written by the core team as they see fit, apart from gnokey, gno, gnodev. Code should contain proper godoc comments and main usage examples.
• Anything with @ or * is up for grabs. I can create starter issues or files for each item in the index with a more informative description of what it is, and a suggested content flow for that item, so someone can take over that file.
• @alexiscolin I will need your help primarily with docusaurus. It would be great to brainstorm a small design revamp, such as changing the UX (point 2 of the Remarks section), possibly the colors, etc. A content revamp will feel much better if the design is also revamped.
• Possibly will need @sw360cab's help for setting up infra.
• Each file/PR will need a review from @gnolang/tech-staff and @gnolang/devrels both, 1) to confirm the technical accuracy, 2) to confirm the readability/style and content/learning flow.

Primary stakeholders here are: @moul, @thehowl, @leohhhn, @gnolang/tech-staff
And of course, anyone who is willing to join the effort is more than welcome.

Related: gnolang/gno#2615

[moul]

why is this issue on this repo?

[leohhhn]

@moul

It felt more appropriate since we would be doing the revamp in this repo, as we discussed; I can move it to the monorepo, but I would like a single repo flow for the whole process (content+framework).

[leohhhn]

Closing this in favor of the issue in the monorepo.