docs.gno.land revamp #2953
Comments
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.
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 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.
Let's use #2357 instead ;)
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).
Ideas for examples (order matters):
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.
Couldn't a lot of these just be part of a glossary?
We can keep what we currently have without many modifications, but this eventually should just be a link to the |
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.
For me, glossary = lookup dictionary - I expect this to be the place where you can read 1-2 sentences for a specific term. |
|
Thanks for putting this together. Looking forward to the revamp. I'll try to provide some thoughts and perspective to see if there is room for iteration. The experience angle:
Going a bit deeper:The docs should have a primary focus that's immediately apparent. It seems smart contract and application developers should be the priority for the developer audience, with the main goal of promoting and enabling smart contract development on gno.land. At the same time, the docs are trying to balance two core themes: Gno as a language and gno.land as a platform. In principle, gno.land is one implementation of what Gno enables. But that's just it—it's an implementation. One of the goals is to encourage forking, alternative interpretations, and modifications. Currently, though, Gno and gno.land are tightly coupled in the docs. There's good reason for this approach, but another perspective is that Gno could have its own docs. This doesn't necessarily suggest a separate set of docs, but rather a structure emphasizing Gno's unique identity. While it makes sense that we can directly reference available Go docs and resources, Gno has its philosophy and identity, which "Gno docs" would both reflect and reinforce. Maybe long-term, but why not now?
Direct reaction to content points made:
I suppose if there are screenshots, they also have overhead for maintenance when updating them.
Should the docs be structured with categories and more abstract headings that "construct the ecosystem" and make it more relatable? Sections like Consensus, Governance, etc.
What if we started with just removing outdated content or hiding content that needs rework while the revamp approach is settled on, to avoid continuing to commit to outdated communication, such as https://docs.gno.land/concepts/proof-of-contribution? |
|
We've started work on a separate repo which we will later launch as the official revamp of the docs. Here is the link, and it's currently restricted access: https://github.com/gnolang/docs-v2 |
Introducing the `r/docs` namespace, where the homepage currently lists subrealms manually. In the future, we may implement a registry, but for now, we’re keeping the source code as lean as possible. The namespace includes several interactive examples to guide users through key concepts. The `r/docs/hello` example provides a simple Render function and invites users to click on "view source" to understand the basics of customization. The `r/docs/avl_pager` example demonstrates path-based interactions, allowing users to explore an avl tree structure with pagination links to navigate between items. Users are encouraged to click on these links for inspiration before manually adjusting parameters in the URL. The added `r/docs/add` example introduces interactivity through transactions, allowing users to adjust a number by submitting transactions, and see the updated result with each interaction. These examples are designed to engage users with Render-based UI interactions, path handling, and transaction-based updates. Once we have more content in r/docs, this section could serve as the main documentation link in the navbar, providing a comprehensive, hands-on introduction to Gno. Addresses #3084 Addresses gnolang/docs-v2#27 (comment) Addresses #2953 --------- Signed-off-by: moul <[email protected]>
Introducing the `r/docs` namespace, where the homepage currently lists subrealms manually. In the future, we may implement a registry, but for now, we’re keeping the source code as lean as possible. The namespace includes several interactive examples to guide users through key concepts. The `r/docs/hello` example provides a simple Render function and invites users to click on "view source" to understand the basics of customization. The `r/docs/avl_pager` example demonstrates path-based interactions, allowing users to explore an avl tree structure with pagination links to navigate between items. Users are encouraged to click on these links for inspiration before manually adjusting parameters in the URL. The added `r/docs/add` example introduces interactivity through transactions, allowing users to adjust a number by submitting transactions, and see the updated result with each interaction. These examples are designed to engage users with Render-based UI interactions, path handling, and transaction-based updates. Once we have more content in r/docs, this section could serve as the main documentation link in the navbar, providing a comprehensive, hands-on introduction to Gno. Addresses gnolang#3084 Addresses https://github.com/gnolang/docs-v2/pull/27#discussion_r1848481556 Addresses gnolang#2953 --------- Signed-off-by: moul <[email protected]>
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
gnowebdown the line.docs-linterto the repo containing content to check for broken links.-helpoutput 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.mdmasterfile 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 forgnowebdown the line.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,gnobinaries, 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 contentewill use embedded playgroundGetting Started
gnoweb+Render()+ md minimalist approach)std,p/demo,r/demo,stdlibs...) *er/demo/userbook(gnokey & connect)@Developer Guides
gnokeygnodev- Full feature showcase @gno- Gno unit tests (covering context manipulation, uassert & urequire,...) e@gnowebisn't enough)gnowebcan provide, or need the service for other reasons)Concepts
Misc (needs better name or make into a no-name section)
Reference
stdreference @ (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.
Moved over from the docs.gno.land repo: gnolang/docs.gno.land#56
The text was updated successfully, but these errors were encountered: