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:** ````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._ - `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:** ```html <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:** ```markdown 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:** ```markdown  ``` ### Headers - Use markdown headers (`#`, `##`, `###`). - Ensure a logical hierarchy (don't skip levels). - `h2` and `h3` are most common for content structure.