Adev Writing GuideSAFE

Deliver web apps with confidence 🚀

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: adev-writing-guide
description: Comprehensive writing guide for Angular documentation (adev). Covers Google Technical Writing standards, Angular-specific markdown extensions, code blocks, and components. You MUST use this skill any time you plan to create, edit, or review documentation files in `adev/` or `adev/src/content`.
---

# Angular Documentation (adev) Writing Guide

This skill provides comprehensive guidelines for authoring content in `adev/src/content`. It combines Google's technical writing standards with Angular-specific markdown conventions, components, and best practices.

## I. Google Technical Writing Guidelines

### Tone and Content

- **Be conversational and friendly:** Maintain a helpful yet professional tone. Avoid being overly casual.
- **Write accessibly:** Ensure documentation is understandable to a diverse global audience, including non-native English speakers.
- **Audience-first:** Focus on what the user needs to do, not just what the system does.
- **Avoid pre-announcing:** Do not mention unreleased features or make unsupported claims.
- **Use descriptive link text:** Link text should clearly indicate the destination (e.g., avoid "click here").

### Language and Grammar

- **Use second person ("you"):** Address the reader directly.
- **Prefer active voice:** Clearly state who or what is performing the action (e.g., "The system generates a token" vs "A token is generated").
- **Standard American English:** Use standard American spelling and punctuation.
- **Conditional clauses first:** Place "if" or "when" clauses before the instruction (e.g., "If you encounter an error, check the logs").
- **Define terms:** Introduce new or unfamiliar terms/acronyms upon first use.
- **Consistent terminology:** Use the same term for the same concept throughout the document.
- **Conciseness:** Aim for one idea per sentence. Keep sentences short.

### Formatting and Organization

- **Sentence case for headings:** Capitalize only the first word and proper nouns in titles and headings.
- **Lists:**
  - **Numbered lists:** Use for sequential steps or prioritized items.
  - **Bulleted lists:** Use for unordered collections of items.
  - **Description lists:** Use for term-definition pairs.
- **Serial commas:** Use the Oxford comma (comma before the last item in a list of three or more).
- **Code formatting:** Use code font for code-related text (filenames, variables, commands).
- **UI Elements:** formatting user interface elements in **bold**.
- **Date formatting:** Use unambiguous formats (e.g., "September 4, 2024" rather than "9/4/2024").
- **Structure:** Use logical hierarchy with clear introductions and navigation. Headings should be task-based where possible.

### Images and Code Samples

- **Images:** Use simple, clear illustrations to enhance understanding.
- **Captions:** Write captions that support the image.
- **Code Samples:**
  - Ensure code is correct and builds without errors.
  - Follow language-specific conventions.
  - **Comments:** Focus on _why_, not _what_. Avoid commenting on obvious code.

### Reference Hierarchy

1.  Project-specific style guidelines (if any exist in `CONTRIBUTING.md` or similar).
2.  Google Developer Documentation Style Guide.
3.  Merriam-Webster (spelling).
4.  Chicago Manual of Style (non-technical).
5.  Microsoft Writing Style Guide (technical).

---

## II. Angular Documentation Specifics

### Code Blocks

Use the appropriate language identifier for syntax highlighting:

- **TypeScript (Angular):** Use `angular-ts` when TypeScript code examples contain inline templates.
- **HTML (Angular):** Use `angular-html` for Angular templates.
- **TypeScript (Generic):** Use `ts` for plain TypeScript.
- **HTML (Generic):** Use `html` for plain HTML.
- **Shell/Terminal:** Use `shell` or `bash`.
- **Mermaid Diagrams:** Use a `mermaid` fenced block. `<docs-code language="mermaid">` is not supported and fails the build.

#### Attributes

You can enhance code blocks with attributes in curly braces `{}` after the language identifier. `header` and `highlight` take a value after a colon; the rest are bare flags, and writing one as `flag: true` fails the build with `Invalid code block metadata`, as does an unrecognized key:

- `header: "Title"`: Adds a title to the code block.
- `linenums`: Enables line numbering.
- `highlight: [2]`: Highlights specific lines. An ascending two-number array is a range, so `[12, 19]` highlights lines 12 through 19. One number, or three or more, is a literal list. Nest one level to mix the two: `[[3,7], 9]`.
- `hideCopy`: Hides the copy button.
- `hideDollar`: Hides the `$` prompt in shell examples.
- `prefer`: Marks code as a preferred example (green border/check).
- `avoid`: Marks code as an example to avoid (red border/cross).

**Example:**

````markdown
```angular-ts {header: "My Component", linenums, highlight: [2]}
@Component({
  selector: 'my-app',
  template: '<h1>Hello</h1>',
})
export class App {}
```
````

#### `<docs-code>` Component

For more advanced code block features, use the `<docs-code>` component. Its attributes use HTML syntax, `attr="value"` with double quotes, and bare names for the boolean ones. It validates nothing, so an unrecognized attribute and a single-quoted value are both ignored without an error:

- `path`: Path to a source file (e.g., `adev/src/content/examples/...`).
- `header`: Custom header text.
- `language`: Language identifier (e.g., `angular-ts`). When omitted, it is inferred from the file extension, and an extension it does not recognize falls back to `angular-ts`, so set it for shell, markdown and scss files.
- `linenums`: Boolean attribute.
- `highlight`: Array of line numbers/ranges, with the same semantics as the fenced form (e.g., `[[3,7], 9]`).
- `visibleLines`: Range of lines to show initially (collapsible).
- `region`: Region to extract from source file.
- `preview`: Boolean. Renders the example as a running component below the code. _Only works with standalone examples.

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

.agent/rules/agents.md

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Adev Writing Guide](https://modelsatlas.com/skills/angular/adev-writing-guide/badge.svg)](https://modelsatlas.com/skills/angular/adev-writing-guide/)

Not your listing, or something out of date? Claim or update your listing.