(WIP) docs revamp.

[raulk]

This reorganizes our docs tree in the following ways:

• Merges inner docs subtrees into a top level docs folder
• Restructures the site docs (docs.ipc.space) into these sections:
  • Overview (could be Introduction)
  • Concepts
  • Getting Started (Setup)
  • Develop (developer guides)
  • Usage (user guides)
  • Troubleshooting
  • Reference (API, SDK, CLI...)
  • Specs (a symlink to docs/specs)

TODO

• Discuss and align on final structure
• Establish redirects from old content to new content (pretty bad for SEO to destroy links)
• Revisit all existing content and re-write/improve/deprecate
• Decide which pieces of new content we need and track those separately

Closes #1287

---

This change is 

[drahnr]

The changes look good, I'd tentatively convert the .PUML files to mermaid diagrams, which do have a textual representation

The files are mostly moved from what I can see, do you intend to do a verification pass, them being still valid/correct?

[raulk]

The changes look good, I'd tentatively convert the .PUML files to mermaid diagrams, which do have a textual representation

Agree, an LLM can probably do this for us.

The files are mostly moved from what I can see, do you intend to do a verification pass, them being still valid/correct?

Definitely not correct -- we need to do a content pass. My initial focus was to contribute a skeleton that consolidated docs assets from all over the repo, and established a good outline/structure for the site. There's a lot of work to do here to get things cleaned up (championed by @LePremierHomme). We have:

• incorrect/outdated content
• poorly communicated content
• missing content

I would, however, discourage a big-bang approach here. Would prefer to merge the skeleton with placeholders and dirty annotations (and even let that go live on the site), then systematically go through each item and improve through smaller, atomic PRs.

[LePremierHomme]

Looks good, few suggestions:

• move site/98-reference/faq.md into site/06-faq (and break sections into files)
• simlink site/98-reference, similarly to specs.
• add placeholder for dev section (not to be published)