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

• Project-specific style guidelines (if any exist in CONTRIBUTING.md or similar).

• Google Developer Documentation Style Guide.

• Merriam-Webster (spelling).

• Chicago Manual of Style (non-technical).

• 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 mermaid .

Attributes

You can enhance code blocks with attributes in curly braces {} after the language identifier:

• header="Title" : Adds a title to the code block.

• linenums : Enables line numbering.

• highlight="[1, 3-5]" : Highlights specific lines.

• hideCopy : Hides the copy button.

• prefer : Marks code as a preferred example (green border/check).

• avoid : Marks code as an example to avoid (red border/cross).

Example:

@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:

• path : Path to a source file (e.g., adev/src/content/examples/... ).

• header : Custom header text.

• language : Language identifier (e.g., angular-ts ).

• linenums : Boolean attribute.

• highlight : Array of line numbers/ranges (e.g., [[3,7], 9] ).

• diff : Path to diff file.

• visibleLines : Range of lines to show initially (collapsible).

• region : Region to extract from source file.

• preview : Boolean. Renders a live preview (StackBlitz). Only works with standalone examples.

• hideCode : Boolean. Collapses code by default.

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> ):

• Must be inside <docs-card-container> .

• Attributes: title , link , href .

• 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), alt .

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:


Headers

• Use markdown headers (# , ## , ### ).

• Ensure a logical hierarchy (don't skip levels).

• h2 and h3 are most common for content structure.