Book Writer

Book Writer

Write source-code-referenced technical books in Markdown with Mermaid diagrams, served as a ProperDocs website. Covers chapter structure, content flow, diagram syntax, and keeping the ProperDocs site in sync with content changes.

ProperDocs Site Maintenance

The book is served via ProperDocs (a MkDocs fork) with the Material theme. When chapter content changes, the site configuration must stay in sync. Forgetting this breaks navigation or hides new chapters from readers.

When you add a new chapter

1. Create NN-slug.md with the chapter template below
2. Add a nav entry to properdocs.yml in the correct Part section:

   - "N. Chapter Title": NN-slug.md

3. Create a symlink in docs/:

   ln -sf "../NN-slug.md" "docs/NN-slug.md"

4. Add a chapter entry to llms.txt in the correct Part section, in chapter order:

   - [Chapter N: Title](https://aospbooks.github.io/aosp-internal-book/NN-slug/): one-line description of what the chapter covers

5. If the chapter number changes existing chapters, renumber the affected properdocs.yml entries and llms.txt URLs too
6. Add the new chapter slug to agents/_content/manifest.toml under the right Part (and create a new Part entry there + agents/_content/parts/<slug>/SKILL.md if the chapter belongs to a brand-new Part), then run python3 agents/build.py and commit the regenerated agents/<platform>/ trees.

When you remove a chapter

1. Delete the .md file
2. Remove its entry from properdocs.yml nav
3. Remove the symlink from docs/
4. Remove the matching llms.txt entry
5. Renumber subsequent chapters if needed (in filenames, properdocs.yml, llms.txt, and section headings inside the files)
6. Remove the chapter slug from agents/_content/manifest.toml, then run python3 agents/build.py and commit the regenerated agents/<platform>/ trees.

When you rename or reorder chapters

1. Rename the .md file
2. Update the properdocs.yml nav entry (both the label and the filename)
3. Update the docs/ symlink
4. Update the llms.txt entry (label, URL slug, and the one-line description if scope changed)
5. Update all ## N.x section headings inside the file to match the new chapter number
6. Update the chapter slug in agents/_content/manifest.toml (and the relevant Part's SKILL.md description if scope shifted), then run python3 agents/build.py and commit the regenerated agents/<platform>/ trees.

properdocs.yml nav structure

The nav groups chapters into Parts. Each Part is a collapsible section in the sidebar:

nav:
  - Introduction: index.md
  - "Part I: Getting Started":
    - "Frontmatter": 00-frontmatter.md
    - "1. Introduction": 01-introduction.md
  - "Part II: Kernel & Boot":
    - "4. Boot and Init": 04-boot-and-init.md

The label format is "N. Short Title": NN-slug.md. Keep labels short — they appear in the sidebar.

docs/ symlinks

ProperDocs reads from docs/ which contains symlinks to the actual chapter files in the repo root. This indirection exists because ProperDocs requires docs_dir to be a child directory, but chapters live at the repo root for simplicity.

When creating symlinks, always use relative paths (../filename.md) so they work regardless of absolute path. Also symlink any static assets the chapters reference.

Chapter Structure

Use this template for every chapter:

# Chapter N: Title

> *Optional opening quote*

Introduction paragraph (no heading).

---

## N.1 First Major Section
### N.1.1 Subsection

## N.X Try It
Hands-on exercises with real commands.

## Summary
Key takeaways as bullets.

### Key Source Files
| File | Purpose |

Example:

# Chapter 9: Binder IPC

> *"Binder is the heart of Android's inter-process communication."*

Android's IPC mechanism enables type-safe, identity-aware communication...

---

## 9.1 Why Binder?
### 9.1.1 One-Copy Semantics

## 9.7 Try It
- Run `adb shell service list` to see all registered Binder services

## Summary
- Binder provides one-copy IPC with caller identity

Content Guidelines

Reference real source code. Every architectural claim should point to a specific file and line — this is what makes the book valuable beyond a generic overview.

// Source: frameworks/base/services/core/.../PowerManagerService.java:202
private static final int DIRTY_WAKE_LOCKS = 1 << 0;

Match code block language to source file extension. AOSP has Go code (.go files in build/soong/) alongside Java. Use ```go for Go code, ```java for Java — never mark Go as Java. Key tells: Go uses :=, func (c *config), []string{}, no semicolons. Java uses ; line endings, public class, @Override.

// Source: build/soong/android/config.go:2402
func (c *config) UseHostMusl() bool {
    return Bool(c.productVariables.HostMusl)
}

Use manual section numbers matching the chapter (## 5.1 for chapter 5). ProperDocs doesn't auto-number, and if you ever generate PDF, Pandoc's auto-numbering doubles manual numbers.

Title format: # Chapter N: Title with colon separator. Not --, not — (em-dash) — those slip in from autocomplete and routine editing and have to be fixed in audit passes.

End every chapter with "Try It" (hands-on exercises) immediately followed by "Summary" (key takeaways). Summary is the last ## section, full stop. Don't append more sections after Summary — not "Appendix", not "Deep Dive", not a new feature you forgot about. If you have extra material, fold it into a numbered section before Try It, or extract it into the standalone appendix file. Reviewers found this drift in 5+ chapters during a single audit pass; it always starts as "just one more section" and degrades the chapter shape.

Watch for duplicate section numbers when inserting new content. Adding a new ## 9.10 between existing sections requires renumbering everything that follows — or you end up with two ## 9.11 headings later in the chapter (real bug found in chapter 9). Skim the full heading sequence after any insertion.

Content Organization

Bottom-to-top for system books — each layer builds on the one below:

Build system → Kernel/boot → Native foundation → HAL → Native services → Runtime → Framework core → Framework features → Connectivity → Security → UI → Apps → Infrastructure → Device support → Practical guide

Mermaid Diagrams

Place a descriptive heading before every mermaid block — it helps readers navigate and becomes the figure caption if you ever generate PDF.

For syntax rules (quoting, special characters, parse errors), read references/mermaid-syntax.md. The short version: quote any node label containing (), <br/>, or |.