cargdev/angular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add no-auto-link instructions to docs style guide (#30980)

Browse Source 
PR Close #30980
This commit is contained in:
Kapunahele Wong 2019-06-11 13:51:34 -04:00 committed by Andrew Kushnir
parent 76584804c8
commit 352f9672c0
1 changed files with 50 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
aio/content/guide/docs-style-guide.md
View File

@ -1,53 +1,53 @@
# Angular Documentation Style Guide # Angular Documentation Style Guide
<!-- formerly Authors Style Guide --> <!-- formerly Authors Style Guide -->
This Style Guide is for anyone who contributes to the Angular documentation (this site). This Style Guide is for anyone who contributes to the Angular documentation (this site).
These guidelines should be followed by all authors. These guidelines should be followed by all authors.
Deviations must be approved by a documentation editor. Deviations must be approved by a documentation editor.
The guidelines described here serve two purposes: The guidelines described here serve two purposes:
* To ensure a high-quality, consistent experience for Angular documentation users. * To ensure a high-quality, consistent experience for Angular documentation users.
* To simplify the writing process for contributing authors. * To simplify the writing process for contributing authors.
This guide helps you make decisions about tone, voice, and style. This guide helps you make decisions about tone, voice, and style.
It also helps you find the right markup quickly. It also helps you find the right markup quickly.
<div class="alert is-helpful"> <div class="alert is-helpful">
This guide is a *living document*; it changes over time. This guide is a *living document*; it changes over time.
We strive for consistency to the extent feasible, but you may find parts of our documentation that don't match this style guide. We strive for consistency to the extent feasible, but you may find parts of our documentation that don't match this style guide.
When in doubt, **follow this guide rather than imitating existing documents.** When in doubt, **follow this guide rather than imitating existing documents.**
</div> </div>
## Scope of these guidelines ## Scope of these guidelines
We ask all contributing authors to adhere to three aspects of style: We ask all contributing authors to adhere to three aspects of style:
* **Writing style:** Word usage, grammar, capitalization, and punctuation. * **Writing style:** Word usage, grammar, capitalization, and punctuation.
Adherence to Angular's writing guidelines ensures a consistent "voice", helps ensure accuracy of the information, and facilitates use world-wide, by audiences with different backgrounds. Adherence to Angular's writing guidelines ensures a consistent "voice", helps ensure accuracy of the information, and facilitates use world-wide, by audiences with different backgrounds.
* **Markup style:** How to include images, tables, alert boxes, and code snippets. * **Markup style:** How to include images, tables, alert boxes, and code snippets.
Angular docs are written in Markdown, with custom extensions for this site. Correct markup ensures a consistent look-and-feel, and is essential for the doc to build and function correctly. Angular docs are written in Markdown, with custom extensions for this site. Correct markup ensures a consistent look-and-feel, and is essential for the doc to build and function correctly.
* **Angular coding style:** Coding style for example apps and code snippets. * **Angular coding style:** Coding style for example apps and code snippets.
Code examples are encouraged for demonstrating how to apply the concepts and features discussed. Code examples are encouraged for demonstrating how to apply the concepts and features discussed.
Angular has a custom framework that enables authors to include code snippets directly from example apps that are automatically tested as part of doc builds. Angular has a custom framework that enables authors to include code snippets directly from example apps that are automatically tested as part of doc builds.
To contribute example code, you must understand Angular itself and the custom framework for Angular doc examples. To contribute example code, you must understand Angular itself and the custom framework for Angular doc examples.
For each aspect of style, the following table explains where to find the primary guidelines and what this Angular Documentation Style Guide offers. For each aspect of style, the following table explains where to find the primary guidelines and what this Angular Documentation Style Guide offers.
Style | Guidelines Style | Guidelines
------------------------ | ------------------------------- ------------------------ | -------------------------------
**Writing style** | Primary: [Google Developer Documentation Style Guide](https://developers.google.com/style/)<br />This guide: Specifies any special considerations for Angular docs. **Writing style** | Primary: [Google Developer Documentation Style Guide](https://developers.google.com/style/)<br />This guide: Specifies any special considerations for Angular docs.
**Markup style** | Primary: This guide<br />This guide: Specifies guidelines for markup of guides and tutorials, which are written primarily in Markdown. **Markup style** | Primary: This guide<br />This guide: Specifies guidelines for markup of guides and tutorials, which are written primarily in Markdown.
**Angular coding style** | Primary: [Angular Style Guide](guide/styleguide "Angular Application Code Style Guide").<br />This guide: How to create, store, and include code examples in guides and tutorials. **Angular coding style** | Primary: [Angular Style Guide](guide/styleguide "Angular Application Code Style Guide").<br />This guide: How to create, store, and include code examples in guides and tutorials.
<div class="alert is-helpful"> <div class="alert is-helpful">
@ -295,8 +295,34 @@ Whatever the source, the doc viewer renders them as "code snippets", either indi
### Code example ### Code example
You can display a simple, inline code snippet with the markdown backtick syntax. You can display a simple, inline code snippet with the markdown backtick syntax.
We generally prefer to display a code snippet with the Angular documentation _code-example_ component Use a single backtick on either side of a term when referring to code or the
represented by the `<code-example>` tag. name of a file in a sentence.
The following are some examples:
* In the `app.component.ts`, add a `logger()` method.
* The `name` property is `Sally`.
* Add the component class name to the `declarations` array.
The markdown is as follows:
```markdown
* In the `app.component.ts`, add a `logger()` method.
* The <code class="no-auto-link">item</code> property is `true`.
* Add the component class name to the `declarations` array.
```
In certain cases, when you apply backticks around a term, it may auto-link to
the API documentation. If you do not intend the term to be a link, use the following
syntax:
```html
The <code class="no-auto-link">item</code> property is `true`.
```
For block code snippets, we generally prefer to display code with
the Angular documentation _code-example_ component represented by the `<code-example>` tag.
See [Code snippets and code examples](guide/docs-style-guide#code-snippets-and-code-samples) for more details.
<h3 class="no-toc">Inline code-snippets</h3> <h3 class="no-toc">Inline code-snippets</h3>