| name | article-tier-audit |
| description | Triage gllvmTMB pkgdown articles into tiers (1 = public worked example, 2 = technical reference, 3 = retire) and judge each against the 10 reader-first style rules. Use when adding, removing, or rewriting any vignette under `vignettes/` or `vignettes/articles/`. |
Article-tier audit
Use this skill whenever the article surface changes: a new article is
added, an existing article is rewritten, an existing article is moved
or retired. The skill is Pat's triage view (the applied PhD-student
user-tester) crossed with the reader-first style rules (rules 1-10
below).
The default tier is 1
Every public article is Tier 1 by default. Tier 2 / Tier 3
require explicit justification.
The legacy package shipped 29 articles and the navbar showed all of
them. The 2026-05-10 audit found that ~10 of those served the
maintainers (validation studies, framework-extension previews,
internal benchmarks) and crowded out the worked-example articles
that served the reader landing from Google. The cure was cutting the
public surface to 7 Tier-1 worked examples plus the Get Started
vignette.
The default presumption is now reversed: a new article must justify
appearing in any tier other than 1. If you cannot answer "what
question does this article answer for a first-time reader?" in one
sentence, the article belongs in Tier 3 (retired) until you can.
The three tiers
Tier 1 -- public worked example (the default)
Serves a first-time reader who landed on this article from Google.
They have a data problem and want to decide (a) whether this model
fits, (b) how to write the code, (c) how to interpret the output.
The exemplar is vignettes/articles/morphometrics.Rmd. Lead with
the user's question, show working code within 30 lines, recover the
truth from the simulation in the same article, end with a
forward-link table.
Tier 1 articles appear in the pkgdown navbar's main "Articles"
dropdown.
Tier 2 -- technical reference
Serves a reader who already knows what gllvmTMB is and needs to
look up the syntax for a specific keyword or families list. Format
is closer to a glossary than a worked example.
Tier 2 articles appear in the pkgdown navbar under a "Technical
reference" sub-dropdown, separated from the Tier-1 articles.
Justify Tier 2 over Tier 1 by writing a one-sentence reason in the
article's YAML front-matter tier: 2 # ...reason....
Tier 3 -- retire
Serves the maintainers, contributors, or reviewers, not the reader
landing from Google. Validation studies, internal benchmarks,
framework-extension previews, PLANNED-mode previews of unsupported
features.
Tier 3 articles do NOT appear in the pkgdown navbar but stay on
disk under vignettes/articles/ so cross-references continue to
work. Mark the YAML front-matter with tier: 3 # ...reason... and
add a one-line note at the article's start saying which Tier-1 or
Tier-2 article supersedes it.
The 10 reader-first style rules (apply to all Tier-1 articles)
- Lead with the user's question, not the math. Open with the
question; the model and math come after.
- Show working code before deriving symbols. Within 30 lines of
the start, the reader should see a
gllvmTMB(...) block that fits
the model the article is about.
- Active voice, present tense. "The model fits" not "the model
is fit".
- One topic per section. One question per paragraph. If you
write "additionally" or "furthermore" twice in a section, split
the section.
- First use of each technical term gets a one-line gloss.
Sigma, Lambda, latent, unique, indep, dep,
phylo_*, spatial_*, animal_*, meta_V -- gloss each at
first use. meta_known_V() is only a deprecated alias.
- End each section with a forward link. A code block the reader
can run, a follow-up question the next section answers, or a
cross-reference to a sibling article.
- Math display is for proofs, not for prose. Inline
$x$ for
passing terms; display $$...$$ only for derivations the reader
needs to follow line-by-line.
- Pictures over tables when comparing more than three rows.
Tables for cross-reference; plots for comparison.
- Cross-reference forward and backward. Articles are read
non-linearly.
- Show the failure mode the article protects against. For
every claim "use this model in case X", briefly show what
happens when X is violated.
Triage criteria (when to retire vs rewrite)
Use this checklist to decide, for any existing article, whether it
should be kept (Tier 1), demoted (Tier 2), or retired (Tier 3):
| Question | Tier | Action |
|---|
| Does the article open with a user-shaped question (rule 1)? | If yes -> 1. If no -> ask the next question. | |
| Could the article be a glossary entry (one keyword's syntax + a code block + 2-3 caveats)? | -> 2 | Move to "Technical reference" sub-dropdown. |
| Does the article validate the package against another implementation, benchmark performance, or preview an unsupported feature? | -> 3 | Retire from navbar. |
| Does the article fail 3+ of the 10 reader-first rules? | -> retire or rewrite | Cheaper to retire if a sibling Tier-1 article covers the topic; rewrite if not. |
The morphometrics article (vignettes/articles/morphometrics.Rmd) is
the canonical Tier-1 exemplar. When unsure how a Tier-1 article
should be structured, read morphometrics first, then write.
Cross-references
_workshop/audits/article-readability-audit.md (Pat's per-article
triage, 2026-05-10) -- read for the worked examples of each tier
judgment._workshop/audits/style-guide-articles.md -- the source for the 10
rules.prose-style-review skill -- for the prose-quality review pass on
any article being reviewed.
