Add docs guideline for Acrolinx VS Code extension (#3842)

This commit is contained in:
Scott Addie 2022-01-27 15:11:55 -06:00 коммит произвёл GitHub
Родитель 09956d10d8
Коммит 36b7b8f3c4
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
2 изменённых файлов: 3 добавлений и 0 удалений

Просмотреть файл

@ -4,6 +4,7 @@
[Azure SDK Contributors Guide]: https://review.docs.microsoft.com/help/contribute-ref/contribute-ref-how-to-document-sdk
[Microsoft Writing Style Guide]: https://styleguides.azurewebsites.net/StyleGuide/Read?id=2700
[Microsoft Cloud Style Guide]: https://styleguides.azurewebsites.net/Styleguide/Read?id=2696
[Acrolinx VS Code extension]: https://aka.ms/azsdk/acrolinx-vscode
[rest-lro]: https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#13-long-running-operations
[general-guidelines]: {{ site.baseurl }}{% link docs/general/introduction.md %}

Просмотреть файл

@ -23,6 +23,8 @@ There are several documentation deliverables that must be included in or as a co
* [Microsoft Writing Style Guide].
* [Microsoft Cloud Style Guide].
{% include requirement/MUST id="general-docs-content-governance" %} use the [Acrolinx VS Code extension] when authoring or editing public-facing Markdown files, such as library READMEs, migration guides, and troubleshooting guides. Changelogs are an exception to this rule. Acrolinx is licensed for use only in the public and private GitHub repos for Tier 1 language SDKs. (MICROSOFT INTERNAL)
{% include requirement/SHOULD id="general-docs-to-silence" %} attempt to document your library into silence. Preempt developers' usage questions and minimize GitHub issues by clearly explaining your API in the docstrings. Include information on service limits and errors they might hit, and how to avoid and recover from those errors.
As you write your code, *doc it so you never hear about it again.* The less questions you have to answer about your client library, the more time you have to build new features for your service.