docs: add README.md in gno.land/pkg/

[grepsuzette]

I made a quick README.md of our packages in gno.land/pkg Submitting as a PR in case it can be useful.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 54.61%. Comparing base (3f5a6ad) to head (6d5c64b). Report is 198 commits behind head on master.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #2321 +/- ## ======================================= Coverage 54.61% 54.61% ======================================= Files 579 579 Lines 77899 77899 ======================================= Hits 42546 42546 Misses 32182 32182 Partials 3171 3171 ``` | [Flag](https://app.codecov.io/gh/gnolang/gno/pull/2321/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=gnolang) | Coverage Δ | | |---|---|---| | [gno.land](https://app.codecov.io/gh/gnolang/gno/pull/2321/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=gnolang) | `61.65% <ø> (ø)` | | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=gnolang#carryforward-flags-in-the-pull-request-comment) to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[thehowl]

@leohhhn Pinging you to decide what to do here.

I tend to like explanations of directory architecture, as documentation within the source (so not in the docs/, but rather as a README item). A project's directory structure becomes second nature after a while developing on a project, so I do see some advantage for newcomers to having something like this instead of learning what is where the hard way.

That said, I see a few problems: such explainers of dir structure tend to fall out of date with no-one realizing it for a few months, so I'm more in favour of something being generated from the package-level comments of each directory. What do you see as most useful?

[moul]

Agreeing with @thehowl, this file makes sense but should be generated. We should focus on writing good documentation in comments and look more frequently at our generated godoc web page.

[grepsuzette]

I don't necessarily see the point of automated doc for this particular case. It's too much work and brings new problems (iatrogenic):

• Automated README.md tend to lack editorial unicity or polish,
• packages are meant to have their own unicity of meaning, style, complexity. They're not supposed to articulate with their sibling packages' single-line-doc, but an automated system will require us to modify them so the result is acceptable (see previous point).

Compare:

Automated:

• bob checks the generated docs (regularly, or when there's a problem or a remark),
• if not ok, bob edits the file(s) in subfolder to edit the one-liner part for the readme,
• bob launches something like make docs
• iterates this list,
• bob creates a Pull Request implying potentially several files,

This system needs to be engineered in the first place, reviewed, tested, maintained. People are also more hesitant to make any change at all to the docs. Automation creates fears of inducing work for others (contributor dilemma: am I helping, or a burden for people doing the work).

---

Manual:

• bob changes one pkg/README.md file (what you see is what you get™),
• bob pushes the PR.
• the PR consists of a few lines to review,
• no sweat if anything missing (a new contributor can always add it later, this README is targetting newcomers as Morgan said).

[leohhhn]

@grepsuzette

bob checks the generated docs (regularly, or when there's a problem or a remark), if not ok, bob edits the file(s) in subfolder to edit the one-liner part for the readme

I think that for this specific case automation is the way forward; code should be well commented and documented in the first place, so having automation just parsing this will be simple. We should default to writing good code comments when making PRs for anything.

So ideally, we could add a script to the CI that will generate the README on every PR that affects that specific folder, keeping everything up to date automatically.

From @thehowl's comment:

such explainers of dir structure tend to fall out of date with no-one realizing it for a few months

This has already happened in the past and we would like to avoid it, which automating this makes sense.

[thehowl]

Mhh, I think we should have here something like this: https://pkg.go.dev/std

Automatically generated, using a one-line explanation directly from the package-level godoc; collapsible or using visual hiearchy to distinguish directories.

Additionally, we can have some visual cues to manually configure the most important packages to know about.

We have a workflow that checks that running go generate creates no diffs in the repository, which we can use to make sure that with each PR the README's stay in sync.

Manual means that things will fall out of date, and then whoever wants to find out information has to follow the paper trail on the repository to find out what happened and what has been renamed to what. I've been there and done that; and honestly I prefer no information rather than incorrect information.

So, my suggestion is to make a tool that when invoked, gets a recursive list of packages and their related one-liner documentation, and then replaces content in a markdown file to have that structure. I'll close this PR and make this as an issue, as it is different from what you're doing here; you're welcome to take it up.