Restructuring AerynOS Documentation (with some AI help)

[chrisdebian]

📚 Proposal: Restructuring AerynOS Documentation

Hi everyone,

I’d like to propose a reorganization of the documentation headings and sidebar navigation to make the docs easier to navigate for both new users and developers. Right now, installation, usage, and packaging content are a little spread out, and this structure would give a clearer flow.

---

🔑 Proposed Top-Level Structure

1. Introduction to AerynOS

2. Getting Started

3. User Guide

4. Package Management

5. Building Packages

6. Development Guide

7. System Architecture

8. Contribution Guide

9. Advanced Topics

10. Reference Materials

11. Community & Support

---

🗂 Recommended Navigation Sidebar Order

👋 For New Users

1. Introduction to AerynOS

What is AerynOS?

Design Philosophy

Key Features

Supported Platforms

2. Getting Started

System Requirements

Installation Guide (ISO, bootable media, step-by-step)

First Boot & Setup (users, networking, configuration)

Quick Start Checklist

3. User Guide

Desktop Environment Basics

System Configuration

Networking & Security

Updating & Upgrading with Moss

---

📦 For Everyday Use

4. Package Management

Overview of Moss

Repositories (stable, unstable, custom)

Installing/Removing/Upgrading Packages

Managing System States & Rollbacks

---

🛠 For Developers & Packagers

5. Building Packages

Introduction to Boulder

Anatomy of a stone.yml

Writing Your First Recipe

Building & Testing Packages

Publishing to Repositories

6. Development Guide

Source Tree Overview

Building AerynOS from Source

Debugging Tools

Automated Testing & CI/CD

7. System Architecture

File System Layout

Boot Process

Update & Rollback Mechanism

Security Model

---

🤝 For Contributors

8. Contribution Guide

How to Contribute

Coding Standards & PR Guidelines

Reporting Bugs & Requesting Features

---

⚙️ Advanced & Reference

9. Advanced Topics

Creating Custom Repositories

Patching Packages

Cross-Compilation

System Hardening

10. Reference Materials

Moss Command Reference

Boulder Command Reference

stone.yml Specification

Licensing & SPDX Guide

Common Errors & Fixes

---

🌐 Community

11. Community & Support

Forums & Discussions

Contributing to Docs

Release Cycle & Roadmap

Contact & Support

---

✅ Benefits

Easier onboarding for new users (clear install → configure → use path).

Packagers and developers get a consistent space with recipes, boulder, and moss workflows.

Contributors know exactly where to find guidelines and references.

---

📌 Next Steps

Gather community feedback on the proposed outline.

If there’s agreement, update mkdocs.yml (or equivalent) with the new sidebar order.

Incrementally reorganize existing docs into the new structure.

---

💬 What do you all think? Would this navigation order make it easier for users, developers, and contributors to find what they need?

Cheers,
Chris

---

[NomadicCore]

Hi Chris,

Are you in the Matrix space per chance as it's easier to discuss there.

In principle I'm open to move things around for a better flow. I note you mention in the title with help from AI. We are working on contributor guidance but we are taking the view of not accepting AI contributions (with a carve out exception if someone has accessibility limitations).

I was wondering if this high level restructuring was using AI or if you're suggesting we use AI to do the work of restructuring for us?

Regards,

NomadicCore