Documentation style guide

Documentation style guide

Documentation StylesDocumentation Styles. The following guides and resources are listed by style, profession, or type of material being cited. Multiple Styles | Citation Management Software | AAA | ACS | AIP. AMA--Management | AMA--Medical | AMS | APA | APS | APSA | ASA Welcome to the Microsoft Writing Style Guide, your guide to writing style and terminology for all communication—whether an app, a website, or a white paper. If you write about computer technology, this guide is for you. Today, lots of people are called upon to write about technology A style guide saves documentarians time and trouble by providing a single reference for writing about common topics, features, and more. The guidelines in a style guide help writers to produce documentation that has the same tone and grammatical style, regardless of who writes the documentation

Welcome - Microsoft Style Guide | Microsoft Docs

This page gives writing style guidelines for the Kubernetes documentation. These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. For additional information on creating new content for the Kubernetes documentation, read the Documentation Content Guide. Changes to the style guide are made by SIG Docs as a group. To propose a change or addition, add it to the agenda for an upcoming SIG Docs meeting, and attend the meeting to participate in the discussion, documentation style guide.

Kubernetes documentation has been translated into multiple languages see Localization READMEs. The way of localizing the docs for a different language is described in Localizing Kubernetes Documentation.

When you refer specifically to interacting with an API object, use UpperCamelCasealso known as Pascal case. You may see different capitalization, such as "configMap", in the API Reference. When writing general documentation, it's better to use upper camel case, calling it "ConfigMap" instead. When you are generally discussing an API object, use sentence-style capitalization. You may use the word "resource", "API", or "object" to clarify a Kubernetes resource type in a sentence.

Don't split an API object name into separate words. For example, documentation style guide PodTemplateList, not Pod Template List. The following examples focus on capitalization. For more information about formatting API object names, review the related guidance on Code Documentation style guide. Code examples and configuration examples that include version information should be consistent with the accompanying text. If the information is version specific, the Kubernetes version needs to be defined in the prerequisites section of the Task template or the Tutorial template.

Once the page is saved, the prerequisites section is shown as Before you begin. To specify the Kubernetes version for a task or tutorial page, include min-kubernetes-server-version in the front matter of the page. If the example YAML is in a standalone file, find and review the topics that include it as a reference. Verify documentation style guide any topics using the standalone YAML have the appropriate version information defined. If a stand-alone YAML file is not referenced from any topics, consider deleting it instead of updating it.

For example, if you documentation style guide writing a tutorial that is relevant to Kubernetes version 1. In code and configuration examples, do not include comments about alternative versions, documentation style guide. Be careful to not include incorrect statements in your examples as comments, such as:. Hugo Shortcodes help create different rhetorical appeal levels. This button lets users run Minikube in their browser using the Katacoda Terminal.

It lowers the barrier of entry by allowing users to use Minikube with one click instead of going through the complete Minikube and Kubectl installation process locally. The Embedded Live Environment is configured to run minikube start and lets users complete tutorials in the same window as the documentation.

Shortcodes will interrupt numbered lists unless you indent four spaces before the notice and the tag. Shortcodes inside include statements will break the build, documentation style guide. You must insert them in the parent document, documentation style guide, before and after you call the include.

For example:. Use a single newline to separate block-level content like headings, lists, images, code blocks, and others. The exception is second-level headings, where it should be two newlines. Second-level headings follow the first-level or the title without any preceding paragraphs or texts. A two line spacing helps visualize the overall structure of content in a code editor better. People accessing this documentation may use a screen reader or other assistive technology AT.

Screen readers are linear output devices, they output items on a page one at a time. If there is a lot of content on a page, you can use headings to give the page an internal structure. A good page structure helps all readers to easily navigate the page or filter topics of interest. Group items in a list that are related to each other and need to appear in a specific order or to indicate a correlation between multiple items.

When a screen reader comes across a list—whether it is an ordered or unordered list—it will be announced to the user that there is a group of list items, documentation style guide.

The user can then use the arrow keys to move up and down between the various items in the list. Website navigation links can also be marked up as list items; after all they are nothing but a group of related links.

End each item in a list with a period if one or more items in the list are complete sentences. For the sake of consistency, normally either all items or documentation style guide should be complete sentences, documentation style guide.

List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by documentation style guide four spaces or one tab, documentation style guide. The semantic purpose of a data table is to present tabular data. Sighted users can quickly scan the table but a screen reader goes through line by line. A table caption is used to create a descriptive title for a data table.

Assistive technologies AT use the HTML table caption element to identify the table contents to the user within the page structure. Using "we" in a sentence can be confusing, because the reader might not know whether they're part of the "we" you're describing. Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.

Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information. An exception to this rule is documentation about announced deprecations targeting removal in future versions. One example of documentation like this is the Deprecated API migration guide. Avoid words like "currently" and "new. Avoid words such as "just", "simply", "easy", "easily", documentation style guide, or "simple".

These words do not add value. Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it on Stack Overflow. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.

Home Available Documentation Versions Getting started Release notes and version skew v1. Documentation Style Guide This page gives writing style guidelines for the Kubernetes documentation. Note: Kubernetes documentation uses Goldmark Markdown Renderer with some adjustments along with a few Hugo Shortcodes to support glossary entries, tabs, and representing feature state.

Note: The website supports syntax highlighting for code samples, but specifying a language is optional. Syntax highlighting in the code block should conform to the contrast guidelines. documentation style guide : v1 earlier versions use kind : Pod Note: Warning, Caution, and Note shortcodes, documentation style guide, embedded in lists, need to be indented four spaces.

See Common Shortcode Issues. Note: Ordered lists that are part of an incomplete introductory sentence can be in lowercase and punctuated as if each item was a part of the introductory sentence. Feedback Was this page helpful? Yes No Thanks for the feedback.

Last modified February 16, at PM PST: update style guide ec5f. Edit this page Create child page Create an issue Print entire section. Use single backticks to enclose inline code. Use triple backticks before and after a multi-line block of code for fenced code blocks, documentation style guide. Use multi-line blocks of code to create diagrams, flowcharts, or other illustrations. Use variable names such as 'foo','bar', and 'baz' that are not meaningful and lack context.

Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well. Set the value of the replicas field in the configuration file. The kubectl handles locating and authenticating to the API server. The kubeadm tool bootstraps and provisions machines in a cluster. kubeadm tool bootstraps and provisions machines in a cluster.

Use first level heading, as Hugo automatically converts the title in the front matter of the page into a first-level heading. Use ordered headings to provide a meaningful high-level outline of your documentation style guide. Use headings level 4 through 6, documentation style guide, unless it is absolutely necessary. If your content is that detailed, it may need to be broken into separate articles.

Use sentence case for headings, documentation style guide. For example, Extend kubectl with plugins. Use title case for headings. For example, Extend Kubectl With Plugins.

Different Style Guides and Citation Formats (MLA, APA, Chicago) - Overview

, time: 10:10

Using a Style Guide for Technical Writing (in )

Google writing style: The Google Developer Documentation Style Guide is a comprehensive resource that this Angular documentation style guide builds upon. Kinds of Angular documentationlink. The categories of Angular documentation include: Guides: much of what's in the documentation section of blogger.com Guides walk the reader step-by-step through tasks to demonstrate concepts and are often 5/12/ · A style guide is a set of standards for writing and designing contents. A style guide for technical writing defines the style that should be used in technical communication, such as in user manuals, online help, and procedural writing. A style guide helps you to write documentation in a clearer way, and to keep a consistent tone of voice and style A style guide saves documentarians time and trouble by providing a single reference for writing about common topics, features, and more. The guidelines in a style guide help writers to produce documentation that has the same tone and grammatical style, regardless of who writes the documentation