Docs: 80% of examples, 5% of tutorials, 15% of other docs.

[moul]

As the title suggests, I propose changing our current focus on documentation. These percentages are arbitrary, and we don't need to target them precisely. However, they reflect my thoughts on "quantity" and the "time we spend."

Let's hold off on writing documentation until we have strong examples. Instead, we should focus on creating impactful examples that feature simple, concise, and well-documented source code. We need to choose variable names carefully to ensure that each example is understandable and useful on its own. Examples should serve as the main documentation, while the docs should act as a curated index of examples. We shouldn't have "grc20 tutorials"; instead, we should offer "getting started tutorials." It's unwise to encourage newcomers to write a grc20 token without a clear utility for it. If people want a token, they can create one using grc20factory. Writing a new contract for grc20 should be driven by plans for additional code that will utilize it. Please remove the "grc20 tutorial" entirely. Instead, create a curated list of "grc20 examples" in the docs/ folder.

This doesn't mean we shouldn't refactor the docs/ folder (#2953); we should do it, and we should do it right now. I just want to emphasize that we shouldn't consider docs/ as the primary place for code to exist. We should focus our "documenter brain" on writing good examples, then good comments in the code implementation, and creating clear unit tests, and providing good func ExampleXXX() to suggest usage. We should be able to provide a link to a contract folder as documentation without any additional information.

We should have only a minimal number of tutorials to help users get started with the tools, such as writing hello world and forum apps (possibly incorporating a grc20 token). After that, we should focus on creating well-titled, targeted examples and develop the habit of producing dedicated examples when we have new ideas or need to express concepts typically included in docs/.

Once we have the examples, we can begin drafting documentation in the docs/ folder that references and links to them.

Effective Gno should be a collection of the most famous and unusual habits on Gno, linking to examples whenever possible.

There is a bounty for those who produce high-quality examples with excellent coding standards. We can provide example folders that are sufficient for understanding. The KPI to measure is their "transformation" efficiency, which reflects how well people grasp the concepts thanks to the examples and how easy it was for them to do so.

I'm also looking for people who want to become full-time grantees to exclusively write simple dApps and packages with this "useful-as-documentation" spirit.

I believe it's better to have very small examples rather than one large one. However, it also makes sense to demonstrate some combinations. Ultimately, we should collectively maintain a meta-realm that incorporates several, if not all, well-known patterns together, like a r/demo/the-big-example. I think I started something like this, but I'm not sure if it was pushed or if it's still a draft PR.

[gfant]

Hi Moul, I would like to work on the idea of simple dApps. I have been working on the Shiken project, but seems like it's not a priority anymore and I would like to do something in GNO that provides value. What type of dApps are you thinking about? Are you thinking about also adding a tutorial on "how to do [dApp]" while doing the dApp to provide more documentation?

[leohhhn]

@gfant

The idea is to create example packages and realms that can be used by learners instead of "written" documentation; the example packages and realms should be well-written & well-tested, and they should showcase the capabilities of Gno. These packages/apps should be easy/relatively easy to understand by people reading them.

Here's a random example that comes to mind - how can closures be used in Gno? There currently exists very few examples of this. I also think that many people (especially developers from other web3 ecosystem, ie people coming from Solidity) don't have much idea what closures are and how they can be used.

[moul]

It can be feature-driven, where the dApp is titled based on its features. As suggested by @leohhhn, we could create a r/docs/closure that includes simple, well-documented code. This would demonstrate not only how to write the code but also how to use it. If possible, it could be interactive, incorporating a Render function and some potential gnokey interactions.

Alternatively, it can be more product-expectation-driven, such as "r/demo/minidex", "r/demo/subscription", "r/demo/memberarea", "r/demo/nft-swap", etc.

[gfant]

So, for example, if I want to show the usage of an avl.Tree in gno, I could write a realm for a waitlist realm/package with a register function, a check if registered, a remove, etc that could be used in other realms and would show all the things an avl.Tree can do?

I would like to know which are the things that are more relevant to start with. Currently the /docs folder contains many things that aren't related to writing examples with realms, as how @moul stated in his first comment.

[moul]

https://github.com/gnolang/gno/pull/3160

[moul]

Meta issue with suggestions: https://github.com/gnolang/gno/issues/3292

[github-actions[bot]]

This issue is stale because it has been open 6 months with no activity. Remove stale label or comment or this will be closed in 3 months.

[github-actions[bot]]

This issue is stale because it has been open 6 months with no activity. Remove stale label or comment or this will be closed in 3 months.