Write Beautiful Docs

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

Start with Chapter 1: Start with a working site. 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 and Deploy. The object indexes below also demonstrate Book publishing features; use them when you need to locate a figure, table, or example.

Contents

Figures

1. Figure 1-1 — Documentation-site illustration. Your Starter preview uses neutral sample content; the first milestone is a site you can open and edit.

Tables

1. Table 2-1 — One explicit order is reused by navigation, paging, and generated contents.
2. Table 6-1 — Each delivery state needs its own evidence and handoff.
3. Table A-1 — One source tree can expose several purpose-specific Book outputs.

Equations

1. Equation 3.1 — A page fails when any one of clarity, accuracy, or consistency falls to zero.

Examples

1. Example 3-1 — The same page now states a prerequisite, a command, and a visible result.