Angular Documentation Authoring Guidelines ​

Before you start ​

Before you start writing documentation, review Google's Tech Writing One, Tech Writing Two, Inclusive Documentation, and Tech Writing for Accessibility.

Writing style goals ​

The audience we're targeting is Developers who have worked on at least one web project before. This means that we assume knowledge of general web platform technologies such as HTML, TypeScript, JavaScript, and CSS.

Orient content around developer intents. Ask yourself "What is the developer trying to accomplish?"

Prefer simple, casual language while remaining technically precise.

Avoid excessive preambles and hand-holding. Let the code examples speak for themselves

Explain things without requiring knowledge of other parts of Angular where possible. Sometimes this is impossible. For example, you have to know something about change detection for lifecycle hooks to make sense. When additional knowledge is necessary, link to the corresponding topics.

Prefer framework-agnostic terminology (e.g. "DOM", "HTML", etc.) when it makes sense, compared to framework-specific terms like "view" or "template". Do use the framework-specific terms when they would be more technically correct.

Content types ​

In-depth guides ​

Example: Components.

• In-depth guides attempt to be fully and completely comprehensive.
• Include recommendations and best practices in their relevant topics.
• In-depth guides are not meant to be read start-to-finish. Expect developers to jump to a specific topic based on what they're trying to learn/accomplish in the moment
• No step-by-step instructions

Tutorials ​

Tutorials are primarily focused on task-based, step-by-step instructions towards a specific goal.

Common pitfalls ​

Several of these pitfalls are covered in Tech Writing One and Tech Writing Two, but we repeat them here because they are very common.

Including and referencing code in documentation ​

• All code examples should follow our team naming practices
• Use descriptive examples grounded in realistic scenarios
  • Generally avoid generic or abstract names like "Comp", "Example", "Hello world", "prop1", etc.
  • Generally prefer examples that reflect realistic scenarios for developers, UserProfile, CustomSlider, etc.
• Avoid pluralizing inline code blocks. You can often accomplish this by adding another noun for what the referenced symbol is.
  • ❌ Bad:: "List all of your @Injectables in the constructor."
  • ✅ Good: "List all your @Injectable dependencies in the constructor"
• Prefer the term "error" over "exception" when talking about JavaScript code (because the JS object is named Error).
• Code examples that use buttons, inputs, links, etc. must follow accessibility best practices
  • All buttons and form controls must have labels
  • Content images must have alt text
  • Any custom UI controls should have appropriate ARIA attributes
  • Any styling should meet WCAG contrast ratio guidelines

Content treatments and when to use them ​

• Callouts
  • Use callouts for a brief aside that offers more context on a topic that's not strictly necessary to understanding the main content
  • Never put multiple callouts next to each other or in proximity (such as separated by one a line or two of text)
  • Never put a callout inside another element, such as a card or table cell
• Alerts
  • Use sparingly to call attention to a very brief but relevant point
  • Never put multiple alerts next to each other or in proximity (such as separated by one a line or two of text)
  • Never put an alert inside another element, such as a card or table cell
• Cards
  • Never nest callouts or alerts inside of cards
• Pills
  • Use pills sparingly for a collection of related links, typically at the end of a section or article