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.

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.

Moved over from the docs.gno.land repo: https://github.com/gnolang/docs.gno.land/issues/56

[thehowl]

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.

The usage by Go is interesting, but also misguided: it seems to actually be used by some automatic tool to create the Go version changelog / release notes.

IMO, using ordering like this can work if we want to have something quick and easy to work with without having to develop too much additional tooling. But I dislike it because the permalink of the file becomes dependent on the ordering; ie. if we want to re-order the sections, the link would break. That's why even in this case, on the hosted documentation I'd prefer if we trimmed the number prefix (but used it only as meta-data for ordering).

Though I think that a file which we can use as a sidebar/navbar can work just as well for barebones usage, like it does for GitHub's wiki sidebar... by changing the CSS, we can also make it collapsable and function as a real side/navbar.

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.

Agreed, ish. IMO, a goal of the content organization using mostly plain text and markdown is to make the docs content "gracefully fallback"; what this means is that even if I cat the file from my terminal I can read the docs, without needing a browser.

Markdown naturally lends itself towards this, and to be fair most users will access through the web, not through a plain-text terminal. But this kind of "graceful fallback" allows us not to get tied to any specific framework or way of showing the content; allowing even a basic render through gnoweb (which is an eventual usecase) to happen without needing to be a full-blown framework.

So, we can add stuff on docs.gno.land; let's just make sure that the content stays as markdown files that gracefully falls back. Then, we can more bells and whistles to the official website.

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.

Let's use #2357 instead ;)

What is gno.land & Gno? Why build with it? *

BTW, me and manfred are writing this, as it's also useful as an internal/company memo. Still a draft, will keep you in the loop (it's a priority).

• Creating a GRC20 token e@

• Creating a .... (GRC721, DAO, ...)

Ideas for examples (order matters):

• Forum (or other kind of discussion-based social)
• DAO (similar to GovDAO, where you can have "decisions as code" using closures)
• Wiki-style with DAO-style Content Moderation
• GRC20

Let's put the focus on applications, using just gnoweb functions, rather than GRC20. Yes, most people will look for GRC20, but we want those that don't know anything about what GRC20 is to care about forums first, before moving onto the financial applications.

Concepts

Couldn't a lot of these just be part of a glossary?

std reference @ (write godoc and generate md)

We can keep what we currently have without many modifications, but this eventually should just be a link to the gno doc web interface.

[leohhhn]

Agreed, ish. IMO, a goal of the content organization using mostly plain text and markdown is to make the docs content "gracefully fallback"; what this means is that even if I cat the file from my terminal I can read the docs, without needing a browser.

Yes, I primarily meant on docusaurus - ie, do you have a sidebar, or a page of items, or something completely different. Markdown content is the source of truth & it has its own order.

Couldn't a lot of these just be part of a glossary?

For me, glossary = lookup dictionary - I expect this to be the place where you can read 1-2 sentences for a specific term. You still have a need for longer concept pages, which is why they have a place in the docs imho. So, for the proposed structure, I would keep the ones I listed.