Skip to content

Commit 6f01461

Browse files
jelbournthePunderWoman
jelbourn
authored and
thePunderWoman
committed
docs: add docs authoring guide (angular#56505)
This new contributor guide includes information for authoring Angular documentation. PR Close angular#56505
1 parent d84d407 commit 6f01461

File tree

1 file changed

+107
-0
lines changed

1 file changed

+107
-0
lines changed

‎contributing-docs/documentation-authoring.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Angular Documentation Authoring Guidelines
2+
3+
## Before you start
4+
5+
Before you start writing documentation, review Google's
6+
[Tech Writing One](https://developers.google.com/tech-writing/one),
7+
[Tech Writing Two](https://developers.google.com/tech-writing/two),
8+
[Inclusive Documentation](https://developers.google.com/style/inclusive-documentation), and
9+
[Tech Writing for Accessibility](https://developers.google.com/tech-writing/accessibility).
10+
11+
## Writing style goals
12+
13+
The audience we're targeting is **Developers who have worked on at least one web project before.**
14+
This means that we assume knowledge of general web platform technologies such as HTML,
15+
TypeScript, JavaScript, and CSS.
16+
17+
Orient content around **developer intents**. Ask yourself _"What is the developer trying to
18+
accomplish?"_
19+
20+
Prefer simple, casual language while remaining technically precise.
21+
22+
Avoid excessive preambles and hand-holding. **Let the code examples speak for
23+
themselves**
24+
25+
Explain things without requiring knowledge of other parts of Angular where possible. Sometimes
26+
this is impossible. For example, you have to know something about change detection for lifecycle
27+
hooks to make sense. When additional knowledge is necessary, link to the corresponding topics.
28+
29+
Prefer framework-agnostic terminology (e.g. "DOM", "HTML", etc.) when it makes sense, compared to
30+
framework-specific terms like "view" or "template". _Do_ use the framework-specific terms when they
31+
would be more technically correct.
32+
33+
## Content types
34+
35+
### In-depth guides
36+
37+
Example: [Components](https://angular.dev/guide/components).
38+
39+
* In-depth guides attempt to be **fully and completely comprehensive**.
40+
* Include recommendations and best practices in their relevant topics.
41+
* In-depth guides are not meant to be read start-to-finish. Expect developers to jump to a
42+
specific topic based on what they're trying to learn/accomplish in the moment
43+
* **No step-by-step instructions**
44+
45+
### Tutorials
46+
47+
Tutorials are primarily focused on task-based, step-by-step instructions towards a specific goal.
48+
49+
## Common pitfalls
50+
51+
Several of these pitfalls are covered
52+
in [Tech Writing One](https://developers.google.com/tech-writing/one) and
53+
[Tech Writing Two](https://developers.google.com/tech-writing/two), but we repeat them here
54+
because they are _very_ common.
55+
56+
| Pitfall | Explanation | ❌ Bad example | ✅ Good example |
57+
|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
58+
| **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." |
59+
| **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" |
60+
| [**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." |
61+
| **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." |
62+
| **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). | | |
63+
| **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. | | |
64+
| **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. | | |
65+
| **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)." |
66+
67+
[active-voice]: https://developers.google.com/tech-writing/one/active-voice
68+
69+
## Including and referencing code in documentation
70+
71+
* All code examples should
72+
follow [our team naming practices](https://github.com/angular/angular/blob/main/contributing-docs/coding-standards.md)
73+
* Use descriptive examples grounded in realistic scenarios
74+
* **Generally avoid** generic or abstract names like "Comp", "Example", "Hello world", "prop1",
75+
etc.
76+
* **Generally prefer** examples that reflect realistic scenarios for
77+
developers, `UserProfile`, `CustomSlider`, etc.
78+
* Avoid pluralizing inline code blocks. You can often accomplish this by adding another noun for
79+
what the referenced symbol is.
80+
* **❌ Bad:**: "List all of your `@Injectable`s in the constructor."
81+
* **✅ Good**: "List all your `@Injectable` dependencies in the constructor"
82+
* Prefer the term "error" over "exception" when talking about JavaScript code (because the JS
83+
object is named `Error`).
84+
* Code examples that use buttons, inputs, links, etc. must follow accessibility best practices
85+
* All buttons and form controls must have labels
86+
* Content images must have alt text
87+
* Any custom UI controls should have appropriate ARIA attributes
88+
* Any styling should meet WCAG contrast ratio guidelines
89+
90+
## Content treatments and when to use them
91+
92+
* **Callouts**
93+
* Use callouts for a brief aside that offers more context on a topic that's not strictly
94+
necessary to understanding the main content
95+
* Never put multiple callouts next to each other or in proximity (such as separated
96+
by one a line or two of text)
97+
* Never put a callout inside another element, such as a card or table cell
98+
* **Alerts**
99+
* Use sparingly to call attention to a very brief but relevant point
100+
* Never put multiple alerts next to each other or in proximity (such as separated by
101+
one a line or two of text)
102+
* Never put an alert inside another element, such as a card or table cell
103+
* **Cards**
104+
* Never nest callouts or alerts inside of cards
105+
* **Pills**
106+
* Use pills sparingly for a collection of related links, typically at the end of a section or
107+
article

0 commit comments

Comments
 (0)