adev-writing-guide

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:

```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.
• hideCode: Boolean. Collapses code by default.
• hideDollar: Hides the $ prompt in shell examples.
• prefer / avoid: Mark the example as preferred or as one to avoid.

Multifile Example:

<docs-code-multifile path="..." preview>
  <docs-code path="..." />
  <docs-code path="..." />
</docs-code-multifile>

Alerts / Admonitions

Use specific keywords followed by a colon for alerts. These render as styled blocks.

• NOTE: For ancillary information.
• TIP: For helpful hints or shortcuts.
• IMPORTANT: For crucial information.
• CRITICAL: For warnings about potential data loss or severe issues.
• TODO: For incomplete documentation.
• QUESTION: To pose a question to the reader.
• SUMMARY: For section summaries.
• TLDR: For concise summaries.
• HELPFUL: For best practices.

Example:

TIP: Use `ng serve` to run your application locally.

Custom Components

• Cards (<docs-card>):
  • Usually inside <docs-card-container>; a single card also renders on its own.
  • Attributes: title, href, link, imgSrc, iconImgSrc, titleInline.
  • href is the destination and link only replaces the default "Learn more" label, so a URL written in link renders as text and a card without href is not clickable.
• Callouts (<docs-callout>):
  • Attributes: title, important, critical.
• Pills (<docs-pill>):
  • Must be inside <docs-pill-row>.
  • Attributes: title, href.
• Steps / Workflow (<docs-step>):
  • Must be inside <docs-workflow>.
  • Attributes: title.
• Tabs (<docs-tab>):
  • Must be inside <docs-tab-group>.
  • Attributes: label.
• Videos (<docs-video>):
  • Attributes: src (YouTube embed URL), title (names the video in the play link's label).

Images

Use standard markdown syntax with optional attributes for sizing and loading behavior.

• #small, #medium: Append to image URL for sizing.
• {loading: 'lazy'}: Add attribute for lazy loading.

Example:

![Alt Text](path/to/image.png#medium {loading: 'lazy'})

Headers

• Use markdown headers (#, ##, ###).
• Ensure a logical hierarchy (don't skip levels).
• h2 and h3 are most common for content structure.