chore(docs): reorganize docs folder, add 404 checker

[leohhhn]

Description

Continuing #1999

Renames the docs with numbers, adds a Go linter and makefile to run it to check for 404 or broken links.

Contributors' checklist...

• Added new tests, or not needed, or not feasible
• Provided an example (e.g. screenshot) to aid review or the PR is self-explanatory
• Updated the official documentation or not needed
• No breaking changes were made, or a BREAKING CHANGE: xxx message was included in the description
• Added references to related issues and PRs
• Provided any useful hints for running manual tests
• Added new benchmarks to generated graphs, if any. More info here.

[moul]

Cool that you added a linter. However, please move it to misc/docs-linter.

Keep this Makefile here.

Thank you.

[moul]

Would be nice to run it from the CI too.

[leohhhn]

Moved the linter: e7546dd

Adding the linter to the CI seems like it is out of scope for this PR - let's leave it for another one.

[leohhhn]

Added the linter to the CI: 8fad8c9

[moul]

Looks good to me.

There is a question on the hierarchy that we need to address later, but this system looks good for both humans and machines, whether on GitHub or from a Go script that would want to generate static pages.

[leohhhn]

I will resolve the merge conflicts after we merge this for consistency

[leohhhn]

I've also added a CI workflow but I'm not fully sure I'm doing it right - any inputs would be appreciated.

[leohhhn]

Staging is returning a 404:
http://staging.gno.land:26657/
http://rpc.staging.gno.land:26657/

@albttx can you check this out?

[moul]

Can you update this branch with master?

Related with #2258

[moul]

Ignore 404 errors when not "localhost".

[moul]

Suggested change

	- name: Run linter
	run: make -C docs/
	- name: Build docs
	run: make -C docs/ build
	- name: Run linter
	run: make -C docs/ lint

[grepsuzette]

I am going to give a few comments and maybe help if I can.

The structure of the PR is currently like:

Our doc reads:

| Gno.land's documentation adopts the Diataxis framework, ensuring structured and predictable content. (...)

Diataxis is like standard doc, with a clear mental model about it.

There's actually a question, by numbering all files and directories are we actually following the guidelines?

For example this screenshot from https://diataxis.fr/complex-hierarchies/:

Diataxis itself says in the end we can what can do whatever we want.

Personally I think:

• Adding numbers to the files in a multi-part tutorial is a good idea.
• Adding numbers to the top folders in docs/ is not ideal.
• Adding numbers anywhere else is plainly normally wrong.

If we put aside the fact ordering can always be done in the markdown, numbering files introduces problems:

Insertion/deletion of a numbered file implies changing references to all subsequent files in the series, in all the docs/ files.

• although doc-linter will help reducing the maintenance burden (eliminating issues/PR because of undetected dead-links),
• changing the references will however still need to be done,
  • for all subsequent files in the numeric series,
  • changing all references in the files in docs/
• since Diátaxis is about to improve docs iteratively, and seamlessly, the numbers will change all the time and it won't be seamless,
• we want documentation to be a joy, not a burden.

So I suggest to abandon this idea of numbered files.

Just for example, the current PR has a file called docs/07-reference/03-stdlibs/01-std/03-coin.md. This is clearly not something we want to maintain.

We usually don't need the numbers. I understand the motivation to order files, but for documentation they should mostly matter for tutorials (you take a lesson with a tutor, since the initiation follows a certain path, numbered files make sense in that case).

According to the theory, if we use Diataxis mindfully, our documentation will evolve iteratively, and four solid poles will remain, not necessarily named like this, with the docs/README.md occupying a very neutral place in the middle:

I propose the following:

• abandon systematic numbering of files in docs/
• use markdown lists to put items in the desired order instead (as shown at the end of this post).
• use README.md as indexes (as discussed in PR 2258),
  • for example, docs/01-overview.md will become docs/README.md
  • this is predictable and reassuring
• make use of leohhhn's doc-linter to detect deadlinks,
• agree to have numbers in long tutorial filenames,
• convene each directory has ideally 4-7 documentative items (already mostly the case),
• convene that not perfect right now is ok,
• trust that everything will fall into place if we use Diataxis guidelines and keep a simple architecture,
• continue to improve the doc iteratively.

This means we can have that as a starting point.

docs/
  README.md
  getting-started/
  how-to-guides/
  concepts/
  reference/
  gno-tooling/
  gno-infrastructure/
  assets/
  legal/
  Makefile

Next iteration, gno-tooling can be moved in reference/tools.
Since gno-infrastructure is some sort of how-to guide, next iteration we can move it there.
This will allow easy and short contributions to the documentation. We don't need to do everything right now.

Also soon enough our docs/README.md will look like this:

gno docs
=======

Welcome to our docs. We are organized like so:

1. Tutorials
2. How to guides
3. Concepts
4. Reference

Not finding what you're looking for?
-------------------

Pellentesque malesuada, ipsum ac mollis pellentesque, risus
nunc ornare odio, et imperdiet dui mi et dui. Phasellus vel
porta turpis. In feugiat ultricies ipsum.

WDYT? Leon, I understand you have already gone through a lot of work in this PR. So I hope my comment is not discouraging. I just think numbered file will cost a lot of work in the future; it's not fair to not say anything. So let's discuss it.

[mvertes]

Numbering all the document files and directories seems a good idea to control their order of appearance, but why are some files / directories not yet numbered?