Skip to content

Commit bfddfe5

Browse files
Bob WatsonAndrewKushnir
Bob Watson
authored and
AndrewKushnir
committed
docs: initial upload of styles used by doc linter (#46897)
Add the configuration and style files to support documentation linting. The `README.md` file includes instructions for installation and use of the lint tool. PR Close #46897
1 parent 3ca9852 commit bfddfe5

108 files changed

Lines changed: 86022 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.vscode/extensions.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,6 @@
1111
// The following extensions are useful when working on angular.io (i.e. inside the `aio/` directory).
1212
//"angular.ng-template",
1313
//"dbaeumer.vscode-eslint",
14+
//"errata-ai.vale-server",
1415
],
1516
}

‎aio/tools/doc-linter/README.md‎

Lines changed: 304 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,304 @@
1+
# Angular documentation lint tool
2+
3+
The files in this directory support the [Vale][ValeMain] documentation lint tool for use while you edit [angular.io][AioMain] documentation files.
4+
5+
*Linting* is an automated process that lint tools, or *linters*, perform to identify stylistic errors in program source code.
6+
Vale is a lint tool that performs a similar analysis of documentation source code.
7+
For more information about lint tools, linting, and their history, see [*Lint* in Wikipedia][WikipediaWikiLintSoftware].
8+
9+
## Use Vale to lint your documentation
10+
11+
[Vale][ValeMain] is an open source, command-line tool that reviews writing style and phrases in your documentation.
12+
You can add it to your integrated development environment \(IDE\) or code editor to test your documentation edits before you submit your pull request.
13+
Using it can help improve the documentation's readability and the consistency of terminology and voice across a range of topics and contributors.
14+
15+
The lint tool is helpful and has been tailored to the Angular documentation style guide.
16+
Unfortunately, it is not as powerful as the grammar and spelling features you find in contemporary document editors.
17+
While Vale helps, it doesn't replace the reviewers that you're currently using to help you write great documentation.
18+
19+
**To use Vale in your documentation:**
20+
21+
1. [Install Vale][AioToolsDocLinterReadmeInstallValeInYourVsCodeIde] in your Visual Studio Code IDE.
22+
To install and use Vale in a different IDE, see [Installation][ValeDocsValeCliInstallation].
23+
2. Fix the problems that Vale identifies in your IDE.
24+
25+
Log any problem you encounter with the documentation linter as a [new docs issue][GithubAngularAngularIssuesNewAssigneesLabelsTemplate3DocsBugYaml] in the repo.
26+
Be sure to specify that this is a linter issue in your description.
27+
28+
## Fix documentation problems identified by Vale
29+
30+
Vale evaluates a markdown \(`.md`\) file when you open it in the IDE and each time you save it. Vale does not review your document as you make changes in it.
31+
32+
When Vale identifies a problem, it can take a simple word substitution or rewriting several sentences or paragraphs to fix it.
33+
Sometimes, you might need to take a step back from the text and consider other alternatives.
34+
35+
To find the best way to fix a problem that Vale identified, think of your reader, be flexible, and keep an open mind.
36+
The documentation should be understood by a range of readers, some of whom might not have much experience with Angular or even web development.
37+
38+
> **Note**
39+
> Remember that when a developer is reading documentation, they are often doing so while thinking about other things, such as coding their Angular application.
40+
> Keeping the docs easy to read, helps developers concentrate on their coding.
41+
42+
These are some tips to help you resolve the issues that the lint tool identifies and to help you make your docs easier to read.
43+
44+
### Refer to the style guides
45+
46+
The lint tool tests against the styles found in these style guides.
47+
Most style tests include links to relevant sections in these documents for more information.
48+
49+
* [Angular documentation style guide][AioGuideDocsStyleGuide]
50+
* [Google Developer Documentation Style Guide][GoogleDevelopersStyle]
51+
52+
> **Note**
53+
> Not every style mentioned in the style guides has a test.
54+
> Style guides and the style tests can change.
55+
56+
### Split up long sentences
57+
58+
Generally, shorter sentences are easier to read than longer ones.
59+
Long sentences can occur when you try to say too much at once.
60+
Long sentences, as well as the use of parentheses, semi-colons, or words identified as *too-wordy*, generally require rethinking and rewriting.
61+
Consider restructuring a long sentence to break its individual ideas into distinct sentences or bullet points.
62+
63+
### Use lists and tables
64+
65+
Sentences that contain comma-separated lists might be clearer if presented as a bulleted-list or table.
66+
Consider changing a comma-separated list of items in a sentence to a list of bullets to make those list items easier to read.
67+
68+
### Use more common words
69+
70+
Shorter, more common words are generally easier to read than longer ones.
71+
This does not mean you need to write down to the audience. Technical docs should still be precise.
72+
Angular docs are read by many people around the world and should use language that the most people can understand.
73+
74+
If you think a specific term is required even though it is been flagged as uncommon, try to include a short explanation of the term.
75+
Also, try adding some context around its first mention.
76+
Linking a term to another section or definition is also an option, but consider the disruption that causes to the reader before you use it.
77+
If you force a reader to go to another page for a definition, they might lose their concentration on the current topic and their primary goal.
78+
79+
### Use fewer words
80+
81+
If you can remove a word and not lose the meaning of the sentence, leave it out.
82+
83+
One common place where removing words can help is in a list of examples with more than two or three items.
84+
Before you place the items in a bullet list, consider if only one of the items can convey the desired meaning.
85+
Another option might be to replace a list of items with a single term that describes all the elements in your list.
86+
87+
### If all else fails
88+
89+
The style rules generally guide you in the direction of clearer content, but sometimes you might need to break the rules.
90+
If you decide that the best choice for the text conflicts with the linter, mark the text as an exception to linting.
91+
92+
If you use these exceptions, please limit the amount of text that you exclude from analysis to the fewest lines possible.
93+
94+
When necessary, you can apply these exceptions to your content.
95+
96+
1. **General exception**
97+
98+
A *general exception* allows you to exclude the specified text from all lint testing.
99+
100+
To apply a general exception, surround the text that you do not want the linter to test with the HTML
101+
`comment` elements shown in this example.
102+
103+
```markdown
104+
105+
<!-- vale off -->
106+
107+
Text the linter does not check for any style problem.
108+
109+
<!-- vale on -->
110+
111+
```
112+
113+
Be sure to leave a blank line before and after each comment.
114+
115+
2. **Style exception**
116+
117+
A *style exception* allows you to exclude text from an individual style test.
118+
119+
To apply a style exception, surround the text that you do not want the linter to test with these HTML
120+
`comment` elements. Between these comments, the linter ignores the style test in the comment, but
121+
still tests for all other styles that are in use.
122+
123+
```markdown
124+
<!-- vale Style.Rule = NO -->
125+
<!-- vale Style.Rule = YES -->
126+
```
127+
128+
Replace `Style.Rule` in the comments with the style and rule from the problem message displayed in the IDE.
129+
For example, imagine that you got this problem message and you want to use the word it identified as a problem.
130+
131+
```markdown
132+
Did you really mean 'inlines'? It was not found in our dictionary. Vale(Angular.Angular_Spelling) [Ln 24, Col 59]
133+
```
134+
135+
The `Style.Rule` for this message is the text inside the parentheses: `Angular.Angular_Spelling` in this case.
136+
To turn off that style test, use the comments shown in this example.
137+
138+
```markdown
139+
140+
<!-- vale Angular.Angular_Spelling = NO -->
141+
142+
'inlines' does not display a problem because the linter does not spell check this text.
143+
144+
Remember that the linter does not catch any other spelling errors in this block of text.
145+
146+
The linter continues to test all other style rules.
147+
148+
<!-- vale Angular.Angular_Spelling = YES -->
149+
150+
```
151+
152+
## Install Vale on your development system
153+
154+
Complete these procedures to install the Vale documentation linter on your development system.
155+
156+
Vale can be installed on Windows, macOS, and Linux, and it can be integrated into many IDEs.
157+
The instructions for installing it into Visual Studio Code on Windows and macOS are summarized here.
158+
For more information, or to install Vale in another IDE or on another operating system, see [Vale installation documentation][ValeDocsValeCliInstallation].
159+
160+
### Prerequisites
161+
162+
Before you proceed, make sure that:
163+
164+
1. You have cloned the [`angular/angular` repo][GithubAngularAngular] on your system. You can work in a fork of the `angular/angular` repo,
165+
but it's easier if your Vale installation uses an up-to-date clone of the `angular/angular` repo.
166+
2. You have a development or writing environment for `angular.io` in the `angular/angular` repo and you can build the `angular.io` docs.
167+
For information about how to create the authoring environment for `angular.io`, see [Angular documentation project][GithubAngularAngularTreeMainAioAngularDocumentationProjectHttpsangulario].
168+
3. You have the required package manager installed on your system. If not, install it before continuing.
169+
* [homebrew][BrewMain] on your macOS system.
170+
* [chocolatey][Chocolatey] on your Windows system.
171+
172+
### Install the Vale command-line tool
173+
174+
Open the following tools on your development system.
175+
176+
1. Open a command-line tool:
177+
* `terminal` on macOS, for example
178+
* `Windows PowerShell` on Windows
179+
2. Open Visual Studio Code.
180+
181+
Follow the instructions for the OS on your development system.
182+
To install Vale on a different OS, see [Installation][ValeDocsValeCliInstallation].
183+
184+
#### Install Vale on macOS
185+
186+
In your command-line tool:
187+
188+
<!-- vale Angular.WriteGood_Illusions = NO -->
189+
<!-- vale Angular.Angular_CliReference = NO -->
190+
191+
1. Run `brew install vale` to install Vale.
192+
2. Get the path to the `vale` application to use as the value of the **Vale > Vale CLI : Path** setting.
193+
1. In the command-line tool, run `which vale`.
194+
Save the returned path for use in the next procedure.
195+
196+
2. If this command does not return a path, restart macOS and repeat this step.
197+
3. Get the path to the configuration file, `vale.ini`, to use in the **Vale > Vale CLI : Config** setting.
198+
1. In the command-line tool, navigate to your `git` working directory with the `angular/angular` repo.
199+
2. Run `git pull` to update the repo.
200+
3. In your clone of the `angular/angular` repo, navigate to the `aio/tools/doc-linter` directory.
201+
4. In the `aio/tools/doc-linter` directory, confirm that you have the `vale.ini` file.
202+
5. Run `pwd` to get the full path to `vale.ini` to use in the next procedure.
203+
204+
<!-- vale Angular.Angular_CliReference = YES -->
205+
<!-- vale Angular.WriteGood_Illusions = YES -->
206+
207+
#### Install Vale on Windows
208+
209+
In your command-line tool:
210+
211+
<!-- vale Angular.WriteGood_Illusions = NO -->
212+
<!-- vale Angular.Angular_CliReference = NO -->
213+
214+
1. Run `choco install vale` to install Vale.
215+
2. Get the path to the `vale` application to use as the value of the **Vale > Vale CLI : Path** setting.
216+
1. In the command-line tool, run `where vale.exe`.
217+
Save the returned path for use in the next procedure.
218+
219+
2. If this command does not return a path, restart Windows and repeat this step.
220+
3. Get the path to the configuration file, `vale.ini`, to use in the **Vale > Vale CLI : Config** setting.
221+
1. In the command-line tool, navigate to your `git` working directory with the `angular/angular` repo.
222+
2. Run `git pull` to update the repo.
223+
3. In your clone of the `angular/angular` repo, navigate to the `aio\tools\doc-linter` directory.
224+
4. In the `aio\tools\doc-linter` directory, confirm that you have the `vale.ini` file.
225+
5. Run `cd` to get the full path to `vale.ini` to use in the next procedure.
226+
227+
<!-- vale Angular.Angular_CliReference = YES -->
228+
<!-- vale Angular.WriteGood_Illusions = YES -->
229+
230+
### Install the Vale extension for Visual Studio Code
231+
232+
This procedure is the same for macOS and Windows.
233+
To install Vale in a different IDE, see [Installation][ValeDocsValeCliInstallation].
234+
235+
<!-- vale Angular.WriteGood_Illusions = NO -->
236+
<!-- vale Angular.Angular_CliReference = NO -->
237+
238+
**To install and configure the Visual Studio Code Vale extension:**
239+
240+
1. In Visual Studio Code, go to the **Extensions** pane.
241+
2. In the Visual Studio Code **Extensions** pane:
242+
1. In the search box, enter `Vale`.
243+
2. In the Vale extension entry, choose, **Install**.
244+
3. Access the settings in Visual Studio Code for the Vale extension.
245+
* On macOS, in the **Code** menu, choose **Preferences**, and then choose **Settings**.
246+
* On Windows, in the **File** menu, choose **Preferences**, and then choose **Settings**.
247+
4. In the **User** settings, navigate to **Extensions > Vale**.
248+
5. Update the Vale extension settings as shown.
249+
* **Vale > Core : Use CLI**, checked.
250+
* **Vale > Server : Lint Context**, `0`.
251+
* **Vale > Server : Provide Fixes**, unchecked.
252+
* **Vale > Server : Server URL**, leave empty.
253+
* **Vale > Vale CLI : Config**, enter the full path to `vale.ini` from the preceding procedure and append the `vale.ini` filename.
254+
* **Vale > Vale CLI : Min Alert Level**, choose `inherited` or `suggestion`.
255+
* **Vale > Vale CLI : Path**, enter the full path of the `vale` application that `which vale` or `where vale.exe` returned in a preceding step.
256+
6. Restart Visual Studio Code to apply the new settings.
257+
258+
<!-- vale Angular.Angular_CliReference = YES -->
259+
<!-- vale Angular.WriteGood_Illusions = YES -->
260+
261+
## Update the Vale command-line tool
262+
263+
* To update Vale on macOS to the latest version, in your command-line tool, run `brew upgrade vale`.
264+
265+
* To update Vale on Windows to the latest version, in a PowerShell window, run `choco update vale`.
266+
267+
## Update the Vale style tests
268+
269+
The style tests are stored in your local clone of the [`angular/angular` repo][GithubAngularAngular] and
270+
are updated automatically when you pull the latest code to your system.
271+
If you're using another branch or fork of the `angular/angular` repo, be sure to also update that branch or fork.
272+
273+
<!-- links -->
274+
275+
[AioGuideDocsStyleGuide]: https://angular.io/guide/docs-style-guide "Angular documentation style guide | Angular"
276+
277+
[AioMain]: https://angular.io "Angular"
278+
279+
[AioToolsDocLinterReadmeInstallValeInYourVsCodeIde]: #install-vale-on-your-development-system "Install Vale | "
280+
281+
<!-- external links -->
282+
283+
[BrewMain]: https://brew.sh "homebrew"
284+
285+
[Chocolatey]: https://chocolatey.org/ "Chocolatey"
286+
287+
[GithubAngularAngular]: https://github.com/angular/angular "angular/angular | GitHub"
288+
289+
[GithubAngularAngularIssuesNewAssigneesLabelsTemplate3DocsBugYaml]: https://github.com/angular/angular/issues/new?assignees=&labels=&template=3-docs-bug.yaml "Issue: Docs or angular.io Bug Report | angular/angular | GitHub"
290+
291+
[GithubAngularAngularTreeMainAioAngularDocumentationProjectHttpsangulario]: https://github.com/angular/angular/tree/main/aio#angular-documentation-project-httpsangulario "Angular documentation project [AioMain] | angular/angular/aio | GitHub"
292+
293+
[GoogleDevelopersStyle]: https://developers.google.com/style "About this guide | Google developer documentation style guide | Google Developers"
294+
295+
[ValeDocsValeCliInstallation]: https://vale.sh/docs/vale-cli/installation "Installation | Vale.sh"
296+
297+
[ValeMain]: https://vale.sh "Vale.sh"
298+
299+
[WikipediaWikiLintSoftware]: https://en.wikipedia.org/wiki/Lint_%28software%29 "Lint (software) | Wikipedia"
300+
301+
<!-- end links -->
302+
303+
<!-- @reviewed 2022-07-15 -->
304+

0 commit comments

Comments
 (0)