Add Author Quickstart chapter for docs-spec-template by wmat · Pull Request #155 · riscv/docs-dev-guide

Bill Traynor (wmat) · 2026-07-16T20:18:11Z

Summary

Adds a new Author Quickstart chapter that walks a spec author through bootstrapping a repository created from docs-spec-template:

Renaming the template (component name/title, PDF assembler, Makefile pointer, bib database) and confirming .docmode.
Where chapter content lives (modules/ROOT/pages/) and the single-source model shared by the PDF and the Antora site.
Why you never duplicate .adoc files, and the two glue files (nav.adoc + the PDF assembler) to keep in lockstep.
Manual steps (numbering rule, site registration, release-time version stamping) vs. what's automatic.
The local build and preview loop, including expected local-preview gaps.

Wired into the book in docs-dev-guide.adoc between the intro and authoring chapters, and formatted to match the existing chapters ([[anchor]] + level-2 title, ===/==== subsections, no per-file TOC).

🤖 Generated with Claude Code

Add a chapter walking spec authors through bootstrapping a repo from docs-spec-template: renaming the template, where content files live, the single-source PDF/Antora model, manual steps, and the local build loop. Wire it into the book between the intro and authoring chapters. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Bill Traynor <wmat@riscv.org>

Kersten Richter (kersten1) · 2026-07-16T21:09:57Z

+
+The single most important idea: your chapter content lives **once**, in
+`modules/ROOT/pages/`. Both the PDF and the site read those same files. What you
+maintain by hand is a one-line _pointer_ to each chapter in two glue files -- not


in two glue files?

Kersten Richter (kersten1) · 2026-07-16T21:19:13Z

+=== Where the content files go
+
+All chapter content goes in `modules/ROOT/pages/`, one file per chapter. Each
+page is a standalone Antora page that starts with a **level-0 title**


they do? level-0 title? that is an h1, right? pretty sure they are all h2s

I don't know why this is highlighted yellow for me so if you see yellow, I dunno - ignore it?

Kersten Richter (kersten1) · 2026-07-16T21:20:19Z

+[source]
+----
+modules/ROOT/pages/
+  index.adoc          <1>


add copyright.adoc after this. or is this something that we will have to add later because it might muck up the PDF?

Let's add copyright in the next PR.

Kersten Richter (kersten1) · 2026-07-16T21:21:04Z

+<3> Front matter.
+<4> Back matter.
+<5> Bibliography database.
+<6> PDF assembler -- glue, not content (see below).


Kersten Richter (kersten1) · 2026-07-16T21:21:52Z

+  heading, reproducing the historical PDF chapter numbering.
+
+So there is no copy to keep in sync. What you _do_ maintain is a one-line pointer
+to each page in **two** glue files. Whenever you add, remove, or reorder a


Kersten Richter (kersten1) · 2026-07-16T21:23:17Z

+(`riscv-admin/antora.riscv.org`), keyed to the **line numbers of the `xref`
+entries in `modules/ROOT/nav.adoc`** -- not by anything in your repo. When your
+nav lines shift, the matching `chapters: {start, end}` entry in the playbook's
+`numbering_rules` must be updated in lockstep, or site numbering silently drifts.


I think you are using lockstep too much. Maybe "at the same time" this time?

Fair enough. I replaced one and left one.

Kersten Richter (kersten1) · 2026-07-16T21:24:49Z

+
+==== Every time you change chapter structure
+
+Update the **central playbook's numbering rule.** This is the easiest step to


I dunno - I think that this shouldn't be in here, unless they have the chaptering ability in their own playbook. Until we are building their stuff, it seems weird that they would come edit it in our central playbook.

Agreed, in fact I'd like to remove it from the playbook altogether somehow.

Kersten Richter (kersten1) · 2026-07-16T21:25:18Z

+
+==== One-time site registration
+
+Your spec must be added as a `content.sources:` entry in the central playbook


this won't happen until after ratification, yes?

Depends if we start exposing dev specs before ratification. I was hoping that issuing a PR against the playbook to add a new spec could fall on the authors.

Kersten Richter (kersten1) · 2026-07-16T21:27:03Z

+make stamp-antora VERSION=vX.Y.Z   # then commit antora.yml
+----
+
+In normal CI this is automated: the release build stamps `antora.yml` and opens a


if this is automated, then why is it in the Manual section?

Kersten Richter (kersten1) · 2026-07-16T21:27:40Z

+No dual-source concern -- just edit these directly:
+
+* `modules/ROOT/pages/index.adoc` -- the site cover / landing page. Replace the
+  abstract placeholder; leave the stamped version and phase attribute lines


what is the abstract placeholder?

Kersten Richter (kersten1) · 2026-07-16T21:29:11Z

+* `modules/ROOT/pages/index.adoc` -- the site cover / landing page. Replace the
+  abstract placeholder; leave the stamped version and phase attribute lines
+  alone.
+* `MAINTAINERS.md`, `CONTRIBUTING.md`, the contributors page, the bib database.


I edit these? is the contribors page contributors.adoc? same with bib database? bibliography.adoc and then the .bib? is that a database?

Kersten Richter (kersten1) · 2026-07-16T21:30:09Z

+  alone.
+* `MAINTAINERS.md`, `CONTRIBUTING.md`, the contributors page, the bib database.
+
+==== Mostly automatic -- don't do these by hand


Mostly automatic? but they don't do these by hand? Maybe call it "Versioning" or something more descriptive of what is happening.

Kersten Richter (kersten1) · 2026-07-16T21:31:05Z

+
+* **Citations and `bibliography::[]` render as raw text** locally. The ASAM
+  bibliography extension exists only in the central playbook. Check citations in
+  the `make` PDF or on the dev site.


they won't be on the dev site until ratified though.

Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: Bill Traynor <wmat@riscv.org>

Bill Traynor (wmat) · 2026-07-16T21:55:12Z

OK I've pushed changes to address your review items, mostly.

Bill Traynor (wmat) requested a review from Kersten Richter (kersten1) July 16, 2026 20:18

Bill Traynor (wmat) self-assigned this Jul 16, 2026

Kersten Richter (kersten1) reviewed Jul 16, 2026

View reviewed changes

Kersten Richter (kersten1) approved these changes Jul 16, 2026

View reviewed changes

Addressing Kersten's review.

4a4bc37

Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: Bill Traynor <wmat@riscv.org>

Bill Traynor (wmat) merged commit 7efc639 into main Jul 16, 2026
5 checks passed

Bill Traynor (wmat) deleted the author-quickstart branch July 16, 2026 22:05


		==== Every time you change chapter structure

		Update the central playbook's numbering rule. This is the easiest step to


		==== One-time site registration

		Your spec must be added as a `content.sources:` entry in the central playbook

Uh oh!

Conversation

Bill Traynor (wmat) commented Jul 16, 2026

Summary

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Bill Traynor (wmat) commented Jul 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants