# Write Beautiful Docs

> A practical tutorial for creating clear, beautiful, and maintainable technical content with OINK.

---

LLMS index: [llms.txt](/llms.txt)

---

*Write Beautiful Docs* is the tutorial companion to the OINK reference. The
reference tells you what each parameter and component does; this book is being developed around one Starter site, from its first local
preview toward a reviewed, published result.

The first three chapters contain working material. Later chapters deliberately
show the Book draft state while their full walkthroughs are being written.

## How to read this book {#reading-path}

Start with [Chapter 1: Start with a working site](/book/01-start/). Chapters
1–3 use the same Starter to preview the site, add bilingual pages, and improve
their content. Chapters 4–6 and the appendix are still draft outlines. To
finish customization and deployment now, continue with the
[Starter tutorial](/docs/start/starter/) and [Deploy](/docs/admin/deploy/).
The object indexes below also demonstrate Book publishing features; use them
when you need to locate a figure, table, or example.

## Contents {#contents}

- [1 Start with a working site](/book/01-start/)
  - [Define the outcome](/book/01-start/#outcome)
  - [Install the prerequisite](/book/01-start/#prerequisite)
  - [Run the preview](/book/01-start/#preview)
  - [Record the baseline](/book/01-start/#baseline)
- [2 Structure the content](/book/02-structure/)
  - [Start from the reader’s questions](/book/02-structure/#reader-questions)
  - [Build the tree](/book/02-structure/#content-tree)
  - [Keep order explicit](/book/02-structure/#ordering)
  - [Make stable addresses](/book/02-structure/#stable-addresses)
- [3 Compose the page](/book/03-compose/)
  - [Give every block one job](/book/03-compose/#one-job)
  - [Start from a small page contract](/book/03-compose/#page-contract)
  - [Measure quality without counting decoration](/book/03-compose/#quality)
  - [Connect the evidence](/book/03-compose/#connect-evidence)
- [4 Shape the experience](/book/04-design/)
  - [Establish the visual hierarchy](/book/04-design/#hierarchy)
  - [Compose the home page](/book/04-design/#home)
  - [Keep navigation predictable](/book/04-design/#navigation)
  - [Design both languages at once](/book/04-design/#languages)
- [5 Choose a publishing surface](/book/05-publishing/)
  - [Match the surface to the reader](/book/05-publishing/#surfaces)
  - [Configure a Blog family](/book/05-publishing/#blog-family)
  - [Turn examples into Case studies](/book/05-publishing/#case-studies)
  - [Keep Book and Docs complementary](/book/05-publishing/#book-and-docs)
- [6 Validate and ship](/book/06-ship/)
  - [Name every delivery state](/book/06-ship/#delivery-states)
  - [Validate the smallest useful surface](/book/06-ship/#validate)
  - [Review the rendered result](/book/06-ship/#visual-review)
  - [Hand off facts, not implications](/book/06-ship/#handoff)
- [A Appendix: Patterns](/book/appendix-patterns/)
  - [Book section root](/book/appendix-patterns/#section-root)
  - [Book chapter](/book/appendix-patterns/#chapter-pattern)
  - [Immersive Blog article](/book/appendix-patterns/#article-pattern)
  - [Generated output matrix](/book/appendix-patterns/#output-matrix)

## Figures {#figures}

- [Figure 1-1](/book/01-start/#fig-first-preview) — Documentation\-site illustration\. Your Starter preview uses neutral sample content\; the first milestone is a site you can open and edit\.

## Tables {#tables}

- [Table 2-1](/book/02-structure/#tbl-reading-order) — One explicit order is reused by navigation\, paging\, and generated contents\.
- [Table 6-1](/book/06-ship/#tbl-delivery-states) — Each delivery state needs its own evidence and handoff\.
- [Table A-1](/book/appendix-patterns/#tbl-output-matrix) — One source tree can expose several purpose\-specific Book outputs\.

## Equations {#equations}

- [Equation 3.1](/book/03-compose/#eq-page-quality) — A page fails when any one of clarity\, accuracy\, or consistency falls to zero\.

## Examples {#examples}

- [Example 3-1](/book/03-compose/#eg-page-contract) — The same page now states a prerequisite\, a command\, and a visible result\.

---

Section pages:

- [Start with a working site](/book/01-start/): Install the prerequisite tools, run a local preview, and establish a visible baseline before changing the design.
- [Give the content a structure](/book/02-structure/): Turn directories, section indexes, page bundles, and weights into one predictable reading and navigation order.
- [Compose a page worth reading](/book/03-compose/): Combine prose, callouts, code, media, tables, and mathematics without turning the page into a component catalogue.
- [Shape the reading experience](/book/04-design/): Turn a sound content structure into a recognizable, responsive, and bilingual publication.
- [Publish more than reference pages](/book/05-publishing/): Use Docs, Blog, Case, Book, and release pages as distinct answers to distinct reader needs.
- [Ship with confidence](/book/06-ship/): Separate local preview, repository integration, theme release, and hosted deployment, then verify each state with the right evidence.
- [Front matter patterns](/book/appendix-patterns/): Copy-and-adapt contracts for Book roots, chapters, immersive Blog posts, and generated Book outputs.

---

Backlinks:

- [Docs](/docs/)
- [Books](/docs/write/book/)