Angular Documentation (adev) Writing Guide

adev/src/content

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

• 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

{}

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

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

<docs-code>

Component

<docs-code>

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

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

Alerts / Admonitions

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

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

• #small

  ,

  #medium

  : Append to image URL for sizing.

• {loading: 'lazy'}

  : Add attribute for lazy loading.

![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.