Closed leohhhn closed 1 week ago
why is this issue on this repo?
@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).
Closing this in favor of the issue in the monorepo.
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
gnoweb
down the line.docs-linter
to the repo containing content to check for broken links.-help
output doc pages. Generally speaking, tool flags should be self-explanatory and understandable to people who know what they’re doing.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 adocs/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):With this approach we can use
docusaurus
' autogenerated sidebar, and we can do the same forgnoweb
down the line.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.Initial structure proposal
Legend:
*
needs to be written mostly from scratch@
needs to be modified or rewritten from existing contente
will use embedded playgroundGetting Started
gnoweb
+Render()
+ md minimalist approach)std
,p/demo
,r/demo
,stdlibs
...) *er/demo/userbook
(gnokey & connect)@Developer Guides
gnokey
gnodev
- Full feature showcase @gno
- Gno unit tests (covering context manipulation, uassert & urequire,...) e@gnoweb
isn't enough)gnoweb
can provide, or need the service for other reasons)Concepts
Misc (needs better name or make into a no-name section)
Reference
std
reference @ (write godoc and generate md)Remarks
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:
gnokey
,gno
,gnodev
. Code should contain proper godoc comments and main usage examples.@
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.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: https://github.com/gnolang/gno/issues/2615