Rework the Flatcar Documentation structure

[t-lo]

The goal of this proposal is to improve our documentation structure (i.e. https://www.flatcar.org/docs/latest/) with the goal of improving accessibility and making it easier to find information.

The proposal mainly concerns the documentation structure. Content will be largely re-used (except for hopelessly outdated content).

For this proposal, I went through the current docs structure, reviewed documentation, and re-grouped information.

Please find below:

1. The new proposed structure. This is meant to be viewed side-by-side with the old structure (below) and/or the live documentation in https://www.flatcar.org/docs/latest/.
2. The current structure. This is how this document started; each item in the structure has an annotation elaborating on where (or if) it ends up in the new structure.

New (proposed) Structure

Overview (NEW; concise description of each section, and pointers to github and Matrix)

Flatcar Concepts and Quick Start

• Brief intro: ease of use / cattle no pets, configure-before-deploy / no config drift, full automation, immutability / in-place updates (NEW)
• Quick Start Guide (formerly "Installing"; potentially extended)
• Tutorial (formerly separate top level item)

Configuration and Provisioning

• Quick overview of config / transpile / deploy workflow (NEW)
• Systemd (units and drop-ins tutorial; from "Set-up and Operation / Using Systemd")
• Butane configuration intro (NEW)
  • [list of items] (from "Set-up and Operation / Common Customisations" )
• Storage set-up
  • [list of items] (from "Set-up and Operation / Storage Set-up", and "Security Options / LUKS" )
• Kernel, Hardware, Drivers, and GPU support
  • Custom / out-of-tree kernel modules (from "Reference / Developer Guides")
  • kernel command line and sysctl (from "Set-up and Operation / Common Customisations / Kernel modules and other settings")
  • Power Management and ACPI (from "Set-up and Operation / Common Customisations")
  • GPU support (from "Set-up and Operation / Common Customisations")
• Securing the system
  • Security and Supply Chain concepts (from "Reference / Supply chain security mechanisms")
  • [list of items] (from: "Setup and Operations / Security Options")
• Customising the Container Runtime
  • docker (from " Container Runtimes / Customizing Docker")
  • podman (NEW; sysext)
  • Authenticating to Registries (from " Container Runtimes / Customizing Docker")
• Automating Deployments with OpenTOFU / Terraform (from "Provisioning Tools / Terraform")

Deploying to Public Cloud, Private Cloud, and Bare Metal

• Deploying to Public Cloud
  • [list, including community images]
  • Amazon ECS (from "Set-up and Operation / Managing Clusters")
• Deploying on Priate Cloud
  • [list, including community images and Incus]
• Deploying on Bare Metal
  • [list, including community images]

Kubernetes

• kubeadm examples
• Node refresh operators for automated updates
• ClusterAPI

In-place updates and roll-backs

• Release channels and in-place update process (NEW, intro)
• controlling updates and reboots (from "Set-up and Operation / Managing Releases")
• Manual roll-back (From "Debugging / Manual roll-back")
• Automated roll-back (NEW)

The Nebraska update server

• Overview
• Deployment
• Manage updates
• Migrate to older versions
• Development
• Internationalization

Customising and Extending the OS image

• System-dependent sysexts (included and optional)
• Sysext Bakery
• Adding bits to the base image (root or OEM)
• Custom kernel modules

Troubleshooting

• [list of items] (mostly from "Debugging")

Developer Guides

• Overview (concise discussion of each sub-section and links to GitHub and Matrix)
• Flatcar Partition Layout (from "Reference / Developer Guides")
• SDK packaging guide (adding software; from "Reference / Developer Guides")
• SDK Kernel development guide (adding / changing kernel configs; from "Reference / Developer Guides")
• Rebuilding the SDK (from "Reference / Developer Guides")
• Building Production Images and Update Payloads (from "Reference / Developer Guides")

Legacy Information

• CLC (from "Provisioning Tools / CLC")
• CGroupsV1 (from "Container Runtimes")
• Flatcar etcd clusters
  • [list of items] (from "Set-up and Operation / Managing Clusters")

Current (existing) structure

And annotations regarding where items end up in the "new" structure.

Overview (basically a huge table of contents)

Installing

• Overview (Quickstart guide, intro to Butane, Ignition) MOVE TO NEW "CONFIGURING AND PROVISIONING" SECTION
• Cloud Providers (AWS, etc.) Regroup, MOVE TO NEW "DEPLOYING" SECTION
• Customizing the Image (modify root fs, pre-populate docker images, OEM) MOVE TO "CUSTOMISE AND EXTEND OS" SECTION
• Virtual Machines (private clouds) Regroup, MOVE TO NEW "DEPLOYING" SECTION
• Bare Metal (ISO, PXE, etc) Regroup, MOVE TO NEW "DEPLOYING" SECTION
• Community Supported Platforms (various) MERGE INTO OTHER VENDORS

Tutorial

• MOVE INTO SUB-SECTION OF "INTRO" SECTION
• Discovering
• Provisioning
• Deploying (which really is "large scale deployments" / infra-as-code with Terraform)
• Updating

Provisioning Tools

• Ignition MOVE INTO BUTANE SUB-SECTION (and add links to go bindings)
• CLC MOVE TO LEGACY
• Butane MOVE TO NEW "CONFIGURING AND PROVISIONING" SECTION
• Sysext (Most information on sysexts) MOVE TO NEW "CUSTOMISING OS" SECTION
• Terraform MOVE TO NEW "CONFIGURING AND PROVISIONING" SECTION
• Torcx REMOVE

Nebraska

• LARGELY KEEP THIS SUB-SECTION (change the section title)
• Overview
• Deployment
• Manage updates
• Migrate to older versions
• Development
• Internationalization

Setup and Operations

• Overview (this is empty)
• Systemd (units and drop-ins tutorial) MOVE TO NEW "CONFIGURING AND PROVISIONING" SECTION
• Common Customisations (Butane config examples, NVIDIA GPU support, HW / Machine specific tuning) MOVE TO NEW "CONFIGURING AND PROVISIONING" SECTION
• Managing Releases (update configuration, channels, locksmith, ...) MOVE TO NEW "In-Place Updates and Rollbacks" SECTION
• Storage set-up (Butane config for setting up storage, LVM, ISCSI, and ZFS sysext) MOVE TO NEW "CONFIGURING AND PROVISIONING" SECTION
• Managing Clusters (largely outdated / edge case documentation on Flatcar ETCD clusters. Nowaday people would use Kubernetes) **MOVE TO "LEGACY" **
• Security Operations (sign-on, ssh, SELinux, FIPS, audit, TPM, CAs, SMT. But also: LUKS!) MOVE TO NEW "CONFIGURING AND PROVISIONING" SECTION
• Debugging (crashn logs, debugging tools, but also: manual version rollbacks!) MOVE TO NEW "TROUBLESHOOTING" SECTION

Container Runtimes

• Docker REMOVE
• Kubernetes (still contains non-sysext alternatives) MOVE TO NEW "KUBERNETES" SECTION
• Incus MOVE TO NEW "DEPLOYING TO CLOUDS..." SECTION
• HA Kubernetes MOVE TO NEW "KUBERNETES" SECTION
• Unified CGroups MOVE TO "LEGACY" SECTION
• Customizing Docker MOVE TO NEW "CONFIGURING AND PROVISIONING" SECTION and add Podman etc.
• Authenticating to Container Registries MERGE WITH "Customizing Docker"

Migrating from CoreOS

REMOVE

Reference

• MOVE most of this to to developer documentation. Kernel module builds should go to "customisation".
• Overview
• Constants and IDs (really. GPT labels and Omaha app ID)
• Developer guides (stuff in here should move up one level)
• dev container / custom kernel modules MOVE TO NEW "CONFIGURING AND PROVISIONING" SECTION
• Integrations (pointer to adopters, various cloud marketplaces (DO's is a 404)) REMOVE
• Unified CGroups MOVE to "Legacy information"

How to contribute

* **REMOVE** / work into Overview and Dev docs

[t-lo]

WIP branch is here: https://github.com/flatcar/flatcar-website/tree/t-lo/docs-restructuring
but it only has the top-level directory structure without content for now.

[sayanchowdhury]

+1 with the new structure. Few points that I was thinking

• Configuration and Provisioning engulfs a lot of information in them, so do we need to break them into smaller chunk. Good thing is we have subcategories so it would be easier to find.
• Let's plan to have a HowTO section listing general end-to-end document to do a job.
• I was looking into your docs search, and it seems like it's not that powerful. We could look into having a good search.