|
| 1 | +--- |
| 2 | +name: devtools-docs |
| 3 | +description: Writing guide for the Angular DevTools documentation site in apps/docs (NgMd). Covers audience, voice, style rules, page types and structure, NgMd authoring components, code samples, checking claims against the code, and the build checks. You MUST use this skill any time you create, edit or review files in apps/docs/src/content, the docs home page, or README.md. |
| 4 | +--- |
| 5 | + |
| 6 | +# Angular DevTools docs writing guide |
| 7 | + |
| 8 | +The human-readable version of this guide is `apps/docs/src/content/contributing/writing-docs.md`. Keep the two in sync when rules change. |
| 9 | + |
| 10 | +The docs are an NgMd site (AnalogJS + Angular + Tailwind + marked). Pages are markdown files in `apps/docs/src/content`. The file path is the URL. The sidebar is `nav` in `apps/docs/src/ngmd.config.ts`. |
| 11 | + |
| 12 | +## 1. Audience and voice |
| 13 | + |
| 14 | +- Readers are Angular developers who have built at least one app. Don't explain TypeScript, the CLI, components, signals or DI basics. Do explain Devframe, MCP and how this project works. |
| 15 | +- Orient each page around what the reader wants to do. |
| 16 | +- Second person and imperative. Present tense. Active voice. |
| 17 | +- One idea per sentence. Short, plain sentences. |
| 18 | +- Condition first: "If X, do Y." |
| 19 | +- Sentence case headings. |
| 20 | +- UI labels in **bold**. Code, files, commands and options in `code`. |
| 21 | +- Descriptive link text, never "here". |
| 22 | + |
| 23 | +## 2. Hard rules |
| 24 | + |
| 25 | +Reviewers reject changes that break these. |
| 26 | + |
| 27 | +1. **No em dashes.** Use a period, comma or parentheses. |
| 28 | +2. **No first person** ("we", "our"). |
| 29 | +3. **No future tense** ("will"). |
| 30 | +4. **No time-relative claims** ("new", "recently", "upcoming", "now supports"). Use a sidebar `status` badge in `ngmd.config.ts` and the changelog instead. |
| 31 | +5. **No comparisons with other devtools products.** Describe this project on its own terms. |
| 32 | +6. **No marketing words**: powerful, seamless, blazingly fast, simply, just, easy. |
| 33 | +7. **No invented features.** Every name, label, option, default, tool and argument must exist in the code. |
| 34 | +8. **Lists with more than one attribute per item are tables.** |
| 35 | +9. **One subject per page.** Link to angular.dev or MDN for background. |
| 36 | + |
| 37 | +## 3. Page types |
| 38 | + |
| 39 | +| Section | Job | Shape | |
| 40 | +| --------------- | ------------------------------------------- | ------------------------------------------------------------------------------ | |
| 41 | +| getting-started | Get one setup running. | Intro, workflow of steps, code per setup, gotchas as callouts. | |
| 42 | +| inspectors | Explain one tab completely. | What it shows, where data comes from, how to use it, agent tools, limits, FAQ. | |
| 43 | +| agents | Reference for MCP server, tools, resources. | Tables of names, arguments, results, grouped by inspector. | |
| 44 | +| guides | One task end to end. | Workflow of steps with full working code. | |
| 45 | +| contributing | Working on the repo. | Commands, tables, checklists. | |
| 46 | + |
| 47 | +Don't mix explainer and tutorial content on one page. |
| 48 | + |
| 49 | +## 4. Page skeleton |
| 50 | + |
| 51 | +```md |
| 52 | +--- |
| 53 | +title: Router |
| 54 | +description: One sentence that summarizes the page. |
| 55 | +--- |
| 56 | + |
| 57 | +<ngmd-hero title="Router" gradient> |
| 58 | + One or two sentences on what the page covers. |
| 59 | +</ngmd-hero> |
| 60 | + |
| 61 | +# Router |
| 62 | + |
| 63 | +Short intro. |
| 64 | + |
| 65 | +## Section |
| 66 | + |
| 67 | +### Subsection |
| 68 | + |
| 69 | +## Where to next |
| 70 | + |
| 71 | +<ngmd-pill-row> |
| 72 | + <ngmd-pill href="/agents/tools" title="Agent tools"></ngmd-pill> |
| 73 | +</ngmd-pill-row> |
| 74 | +``` |
| 75 | + |
| 76 | +- One `#` heading, matching `title`. `##` sections with `###` subsections so the TOC has depth. Don't skip levels. |
| 77 | +- Headings are unique within a page. |
| 78 | +- Before renaming a heading, grep `apps/docs/src/content` for its anchor. Anchors are the slug of the heading text (lowercase, non-alphanumerics to `-`), badges excluded. |
| 79 | +- Add new pages to `nav` in `ngmd.config.ts`. |
| 80 | +- `<ngmd-hero logo="...">` only on pages about one external tool (NgRx, Analog, Vite, Express, Chrome, MCP, Nx). |
| 81 | + |
| 82 | +## 5. Components |
| 83 | + |
| 84 | +Raw HTML in markdown. Always write explicit closing tags; never self-close custom elements. |
| 85 | + |
| 86 | +| Component | Use for | Attributes | |
| 87 | +| ---------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------- | |
| 88 | +| `ngmd-hero` | Page opener, once, before `#`. | `title`, `gradient`, `logo` | |
| 89 | +| `ngmd-callout` | Short aside. | `type`: info, tip, success, warning, danger. `title` | |
| 90 | +| `ngmd-alert` | One point the reader must not miss. | `severity`: info, helpful, important, warning, critical. `label` | |
| 91 | +| `ngmd-card-grid` > `ngmd-card` | Related pages, requirements, overviews. | grid `columns`. card `title`, `link`, `cta`, `icon`, `image`, `avatar` | |
| 92 | +| `ngmd-workflow` > `ngmd-step` | Ordered steps. | step `title` | |
| 93 | +| `ngmd-accordion` > `ngmd-accordion-item` | FAQ. | item `title`, `open` | |
| 94 | +| `ngmd-pill-row` > `ngmd-pill` | Related links at the end of a page. | pill `href`, `title` | |
| 95 | +| `ngmd-badge` | Status chip next to a heading. | `variant`: new, updated, alpha, beta, stable, deprecated | |
| 96 | +| `ngmd-tabs` > `ngmd-tab` | Alternatives a code group can't express. | tab `title`, `icon`, `image` | |
| 97 | +| `ngmd-image`, `ngmd-video` | Screenshots, YouTube or Vimeo. | image `src`, `alt`, `caption`, `width`. video `src`, `title` | |
| 98 | + |
| 99 | +Card icons: book, box, code, compass, file, layers, lightbulb, palette, rocket, search, settings, shield, sparkles, terminal, wrench, zap. |
| 100 | + |
| 101 | +Rules: |
| 102 | + |
| 103 | +- Callouts and alerts are rare. Never adjacent, never inside a card, table cell or other component. |
| 104 | +- Only nest the parent > child pairs above. |
| 105 | +- If the page doesn't make sense without it, it's not a callout. |
| 106 | +- End with a pill row or a card grid, not both. |
| 107 | +- Inside components use HTML (`<code>`, `<strong>`, `<a>`); markdown doesn't render there. Write `@` as `@`. |
| 108 | +- Raw HTML external links need `target="_blank" rel="noopener noreferrer"` or the build fails. Markdown links get it automatically. |
| 109 | +- `*Angular`, `*Analog`, `*Devframe`, `*NgRx`, `*MCP`, `*Vite` are keyword links (`keywords` in `ngmd.config.ts`). The asterisk is intentional. Never "fix" it. |
| 110 | + |
| 111 | +## 6. Code samples |
| 112 | + |
| 113 | +- Always set the language. Put the file path in a comment on the first line: `// src/app/app.config.ts`. |
| 114 | +- Highlight lines with `{3}` or `{2,5-7}` after the language. Count the path comment as line 1. |
| 115 | +- Install commands use a code group: ` ```bash group="install" name="pnpm" active ` then npm, yarn, bun. |
| 116 | +- `file="path#L5-L20"` imports a real file (relative to `apps/docs`, nothing outside it). It is not a title. |
| 117 | +- Samples must run: every import, real export names from `packages/ng-devtools/package.json`, real option names and defaults. |
| 118 | +- Source samples from the demos: `src/` (Angular Travel) and `examples/analog`. |
| 119 | +- Load the overlay only in dev, with the `ngDevMode` dynamic import used on the installation page. |
| 120 | +- Secure by default: no `auth: false` or `allowedOrigins: false` in copyable code unless the page explains it. |
| 121 | +- UI code in samples follows accessibility basics: labels on controls, alt text on images. |
| 122 | +- Realistic names (`TripSearch`, `authGuard`), no `Foo` or `prop1`. Comments explain why, and most samples need none. |
| 123 | + |
| 124 | +## 7. Check claims against the code |
| 125 | + |
| 126 | +| Page | Source of truth | |
| 127 | +| ------------------ | ------------------------------------------------------------------------------------------------- | |
| 128 | +| inspectors/\* | `app/src/pages/*.ts` (the tab) and `packages/ng-devtools/src/*` (collectors, actions) | |
| 129 | +| agents/\* | `packages/ng-devtools/src/devframe.ts`, `rpc/*.ts`, `rpc/analog-register.ts`, Devframe built-ins | |
| 130 | +| getting-started/\* | `packages/ng-devtools/package.json` exports, `hub.ts`, `vite.ts`, `overlay.ts`, `popup.ts`, demos | |
| 131 | +| security | `hub.ts`, `vite.ts`, `forms-privacy.ts`, `forms-actions.ts`, router and Analog redaction | |
| 132 | +| contributing/\* | root `package.json`, `nx.json`, `project.json` files, `.github/workflows`, `extension/` | |
| 133 | + |
| 134 | +Check names exactly. When code changes, update the docs in the same PR. When unsure, say less rather than guess. |
| 135 | + |
| 136 | +## 8. Verify |
| 137 | + |
| 138 | +From the repo root: |
| 139 | + |
| 140 | +1. `pnpm docs:dev` and open every changed page (TOC, links, dark mode). |
| 141 | +2. `pnpm docs:build` (link and anchor guards). |
| 142 | +3. `pnpm format:check` from the repo root. It checks content markdown too, so run `pnpm exec prettier --write` on the pages you changed. |
| 143 | +4. Grep changed files for `—`, "will ", "we ", "new ", "recently", "simply", "just ". |
0 commit comments