Restructure Docs

[glarizza]

@glarizza Take a look at A Tour of Tokio for a good example of how I think we should structure the "first thing" people use to learn about Holos. I'm not sure this should be the quickstart or not, but a concise overview with key concepts is what we need most right now.

Also pretty good: https://tokio.rs/tokio/tutorial

[glarizza]

@jeffmccune Do you think we should have a separate "Overview" or "Tour" section that sits before the Quickstart that guides people through the basic concepts and then routes them to the appropriate guide/pages based on their use-case or persona?

[jeffmccune]

@glarizza No, my question is should we copy the structure entirely? My instinct is yes, I'm looking for a second opinion.

[glarizza]

Pasted from a Slack conversation between Jeff and I:

---

Can we simplify our own docs down to three categories:

1. Tutorial with a linear path from start to finish broken into discrete pages each covering a focused topic. The purpose is to provide a tour of the key pieces of functionality in Holos, each page topic is a stop along that tour.
2. Second section dedicated to stand-alone topics that come up. The idea of recipes could fit in here. "self-contained articles related to various topics that come up as you write platform code with Holos." The obvious first one is moving Fleets and Clusters from the Author API into a stand-alone article. Here's how you iterate over multiple clusters applying a component to each with slight variation. Here's how you add your own field to model an attribute of your cluster.
3. Third section: API Docs, these are auto-generated and we have them.
4. A glossary which can serve as our concepts page and our domain specific language page.

Regarding the tour/tutorial/whatever we want to call it, it should start with an overview that grabs them:

1. One paragraph and a few bullet points on what Holos is.
2. Section with ~2 paragraphs, 3 thoughts each paragraph on the role Holos takes in your organization.
3. Advantages of using Holos. (We had those previously. Safe, Consistent, something else)
4. When not to use Holos (Maybe, not sure we know this yet)
5. Getting help

The second page should dive right into actually doing something with it. This is where we should likely break down the Helm guide and move the pieces to different pages starting here. The first page should be how do I get a basic platform structure in place and rendering? So the second is a "setup" and it should cover holos generate platform and probably render one helm chart so they actually get something done.

Their (https://tokio.rs/tokio/tutorial/setup) setup page maps to our current Installation page plus the holos generate platform command tucked away in the helm guide.

The third page is where the reader actually does something, the hello world.

The fourth page is where we start introducing concepts. Here's where you can start to provide some guidance, I'm not sure what's best but from this point to the end of the tutorial is just concept after concept. Probably using Kustomize to mix in common labels to podinfo?

From here I think we need a ranked list of concepts/features and we just make a page for each starting with the most important.

[glarizza]

Okay, so:

1. Edit holos/doc/website/sidebars.ts and holos/doc/md/**/* with the structure changes
2. Changes to those files in main get mapped to https://holos.run/docs/next/
3. Use absolute imports and global assets
4. Once we get the site the way we want it, you will cut a new version, it will (likely) live at doc/website/versioned_docs/version-v1alpha5, and we will map the live site to the new version when we do the cutover.

[glarizza]

I'll be working out of the 301-docs-structure-refactor branch. I have the bones of the new layout started with the Overview in the Tutorial section.

[jeffmccune]

I'm working a couple of hours tonight, basing my jeff/301-clarify-quickstart branch on yours, hope to land it so you can rebase on main in the morning.

Message ID: @.***>

[jeffmccune]

I landed the structural changes with almost entirely blank placeholders for everything. I ended up removing your commit because make website was complaining about broken links so it was easier to just rename md to md.archive and start fresh with blank files.

[glarizza]

I rebased 301-docs-structure-refactor against main and have been pushing to that branch. If/when you finish with v1alpha5 and want to start digging into the docs, feel free to continue the work started in that branch.

[glarizza]

Closing this out in favor of smaller issues