Elgato_dark/angular
1
0
Fork 0
mirror of https://github.com/angular/angular synced 2026-05-24 09:28:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: cover time-based statements in docs authoring guide (#57536)

Browse source 
Adds some additional guidance on writing content that is tied to a
specific version or point in time.

PR Close #57536
This commit is contained in:
Jeremy Elbourn 2024-08-26 14:18:11 -07:00 committed by Alex Rickabaugh
parent 055e0d9835
commit 7f42e69149
1 changed files with 11 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
contributing-docs/documentation-authoring.md
View file

@ -53,16 +53,17 @@ in [Tech Writing One](https://developers.google.com/tech-writing/one) and
[Tech Writing Two](https://developers.google.com/tech-writing/two), but we repeat them here
because they are _very_ common.
| Pitfall | Explanation | ❌ Bad example | ✅ Good example |
|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| **First person language** | Prefer second person language ("you"), including imperative language. | "We can use the `afterRender` function to register a callback." | "Use the `afterRender` function to register a callback." |
| **Past or future tense** | Always use present tense. This is especially common for future tense with "will". | "The query will return an instance of the component." | "The query returns an instance of the component" |
| [**Passive voice**][active-voice] | Prefer active voice. This often involves changing the order of words in a sentence or making a sentence imperative. | "Your template is compiled to JavaScript by Angular." | "Angular compiles your template to JavaScript." |
| **Mixed content types** | Guides should explain a topic, while tutorials walk readers through a set of step-by-step instructions. Avoid mixing these two content types. | "To define styles for a component, first..." | "Components include CSS styles via the `styles` and `styleUrl` properties." |
| **Topic scope creep** | Each topic should stay focused on one specific subject matter. Don't explain concepts that are better explained elsewhere, especially for web platform behaviors that are best explained by more general sites like [MDN](https://developer.mozilla.org). | | |
| **Nested treatments** | angular.dev supports several custom treatments like callouts, alerts, pills, etc. Do not nest these treatments. Do not use these treatments inside table cells. | | |
| **Lists that should be tables** | Any collection of items that includes more than one piece of information should be a table instead of a bulleted list. | | |
| **Non-descriptive links** | The text of a link should describe the linked content. This is an important accessibility consideration. | "Report all security vulnerabilities [here](https://bughunters.google.com). | "Report all security vulnerabilities to [Google's Vulnerability Bounty Portal](https://bughunters.google.com)." |
| Pitfall | Explanation | ❌ Bad example | ✅ Good example |
|------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| **First person language** | Prefer second person language ("you"), including imperative language. | "We can use the `afterRender` function to register a callback." | "Use the `afterRender` function to register a callback." |
| **Past or future tense** | Always use present tense. This is especially common for future tense with "will". | "The query will return an instance of the component." | "The query returns an instance of the component" |
| [**Passive voice**][active-voice] | Prefer active voice. This often involves changing the order of words in a sentence or making a sentence imperative. | "Your template is compiled to JavaScript by Angular." | "Angular compiles your template to JavaScript." |
| **Mixed content types** | Guides should explain a topic, while tutorials walk readers through a set of step-by-step instructions. Avoid mixing these two content types. | "To define styles for a component, first..." | "Components include CSS styles via the `styles` and `styleUrl` properties." |
| **Topic scope creep** | Each topic should stay focused on one specific subject matter. Don't explain concepts that are better explained elsewhere, especially for web platform behaviors that are best explained by more general sites like [MDN](https://developer.mozilla.org). | | |
| **Nested treatments** | angular.dev supports several custom treatments like callouts, alerts, pills, etc. Do not nest these treatments. Do not use these treatments inside table cells. | | |
| **Lists that should be tables** | Any collection of items that includes more than one piece of information should be a table instead of a bulleted list. | | |
| **Non-descriptive links** | The text of a link should describe the linked content. This is an important accessibility consideration. | "Report all security vulnerabilities [here](https://bughunters.google.com). | "Report all security vulnerabilities to [Google's Vulnerability Bounty Portal](https://bughunters.google.com)." |
| **Making statements relative to a specific point in time** | Docs should describe the framework as it exists _now_, never relative to a specific point in time. Docs should avoid referring to anything as "new" or "recent". Docs should avoid mentioning "upcoming" or "future" changes. | "Angular v18 recently introduced fallback content for ng-content." | "The ng-content element allows you to..." |
[active-voice]: https://developers.google.com/tech-writing/one/active-voice