Reference, Style Guide

Introduction

This style guide contains style conventions on how to write and format content for articles, blogs, guides, and videos for publishing on the Tanzu Developer Center. It is written exclusively for contributors who want to create content for the Tanzu Developer Center.

This style guide is meant to extend the formal VMware Style Guide. For items not discussed explicitly in this guide, refer to that one.

Also, if you are mentioning VMware Tanzu at all in your post, please refer to the VMware Tanzu Branding Guidelines Document.

For specific information on how to prepare content for publishing on the Tanzu Developer Center, refer to the following topics in this style guide.

• See Headings for information on how to use headings.
• See In-Line Code Formatting for information on markdown formatting for In-Line Code.
• See Code Blocks for information on how to use Code Blocks.
• See Bold for information on markdown formatting for Bold.
• See Unordered Lists for information on markdown formatting for Unordered Lists.
• See Ordered Lists for information on markdown formatting for Ordered lists.
• See Note or Warning Callouts for information on when to make content a callout.
• See Images for information on when to use images and when to use code blocks for content.
• See Proper Nouns, Product, and Tool Names for instructions on how to format proper nouns and link them to external websites in your content.
• See Markdown Reference for various examples of markdown.

Headings

Headings provide structure and serve as visual points of reference in a document. A good heading introduces a topic to your audience in an interesting way.

A good heading also:

• Is short and specific.
• Does not include ampersands (&).
• Does not include abbreviated words.
• Is followed by a topic and not another heading. Avoid adding two headings in a row without text in between.
• Goes in order of heading levels. Avoid jumping heading levels (i.e. jumping from H2 headings (##) to H4 (####)

Heading Levels

There are four heading levels that you can use when creating content for the Tanzu Developer’s Center.

• Heading 1 (#): This is the title heading that is automatically generated from the title metadata front matter.
• Heading 2 (##): A second-level heading that is a subsection of Heading 1. Use it to define other topics related to the main topic in Heading 1.
• Heading 3 (###): A third-level heading that is a subsection of Heading 2. Use it to define other topics related to the topic in Heading 2.
• Heading 4 (####): A fourth-level heading that is a subsection of Heading 3.Use it to define other topics related to the topic in Heading 3.

Heading Capitalization

• Headings should be "sentence case". This means capitalization should follow standard sentence structure of the first letter of the first word being capital, with all other words being lower case. Exception for proper nouns, etc.
• Headings should not include an ending punctuation generally, especially periods (.). Exception for excavation points and question marks in instances where the heading is closer to a complete sentence, as opposed to one to three words.

See the Headings section of the Marketing Editorial Style Guide for additional information on how to style headings. See also this markdown reference.

Rule	Example
Use headings as a way to break up your post into consumable and actionable chunks.	## Implementation All source code described in this article as well as an example usage is available here. The RemoveUnusedPdxTypesFunction: * Gets a copy of all PdxTypes * Iterates each input region’s PdxInstance values ### Get All PdxTypes The PdxTypes are stored in a replicated Region called PdxTypes.

In-Line Code Formatting

Use in-line code format in the following scenarios.

NOTE: See the section In-Line Code Formatting for instructions on In-line Code markdown formatting.

Rule	Example
Describe CLI tools or commands in a paragraph.	Later, you will `init` the `tanzu` CLI to to spin up a management cluster.
Describe method/function names in a paragraph.	The `TimingGatewayEventFilter` implements the `GatewayEventFilter` interface to calculate queue transmission.
Describe a JSON/YAML path in a paragraph.	I’ll use `wavefront.geode.jhuynh` to distinguish my stats from others.
Describe a Java or other code path in a paragraph.	In this implementation, it is `com.github.jhuynh1.geode.wavefront.GeodeWavefrontPublisher`.
Describe a library or dependency in a paragraph.	In this case, we need to add the `micrometer-wavefront-registry` with our code.

Do not use an in-line code format in the following scenarios.

Rule	Example
Use a full CLI command to copy and paste the commands. (use Code Blocks instead)	Create a region where we want the data to end up in: ```sh create region –name=’Events’ –type=PARTITION ```

Code Blocks

Use code blocks in the following scenarios. In most cases, the language is specified for syntax highlighting.

Rule	Example
Use a full CLI command to copy and paste the commands.	Create a region where we want the data to end up in: ```sh create region –name=’Events’ –type=PARTITION ```
Show the code which defines a method.	```java public void beforeEnqueue() { this.stats.incLong(queuedEventsId, 1); } ```

For markdown formatting for Code Blocks, see this markdown reference.

Category Names

Apply a bold style to category names including API names that appear in your blog or guide.

See the Bold section below for more information on markdown formatting for Bold.

Rule	Example
Bold Region names.	There are mainly two different kinds of regions: **replicated** and **partitioned**. Each is implemented differently.
Bold names of official patterns or algorithms.	The **Command Pattern** is a behavioral design pattern where an object is used to encapsulate the information needed to perform an action or trigger an event.

Descriptive, Unordered Lists

Descriptive, unordered lists combine multiple markdown formats. Examples include an unordered bulleted list and bolding the name of an item to be described.

Rule	Example
Describe prerequisites in a guide.	## Prerequisites These are things that should be installed prior to proceeding in this blog post * **kubectl** -- You will use this to manage your Kubernetes cluster. Installation instructions are here
Describe methods and their function.	The interface defines three methods: * **`beforeEnqueue`** -- Invoked before the GatewayQueueEvent is added to the queue `beforeTransmit` is invoked... * **`beforeTransmit`** -- Invoked after the GatewayQueueEvent is removed from the queue but before it is transmitted to the remote site. * **`afterAcknowledgement`** -- Invoked after the GatewayQueueEvent acknowledgement is received from the remote site.

Ordered Lists

Ordered lists are often used in guides to help readers follow a series of steps to complete a process. Here, an ordered list should be used. In markdown, if assets (for example, images or code blocks) are inserted in the middle of an ordered list, it could throw off formatting. Therefore, in most cases, it is recommended to explicitly use the step number intended in the list.

Rule	Example
A list with an image embedded in between steps	1. Open the file containing the Linux mascot. 2. Marvel at its beauty.  3. Close the file.

For additional information on styling lists, see the Lists section of the Marketing Editorial Style Guide

For markdown formatting for Ordered Lists, see this markdown reference.

Note or Warning Callouts

Use a note or warning to call out a potential effect or impact of running a command.

• Insert the callout on its own line.
• Make the callout bold. For example, Note or **Warning. **Do not make bold the text that describes the reason for the callout.
• Use an en dash (–) between the callout word and the text that describes the reason for the callout.
• Use complete sentences when writing the reason for the callout.

Rule	Example
Use a callout like a note or a warning to make critical or specific content stand out to your readers.	{{% callout %}} CALLOUT TEXT HERE {{% /callout %}}

Images

Images show GUI functionality or views when necessary, or other use cases where a simple test interface will not work.

NOTE: Use code blocks to show code or CLI commands with output. Do not use images.

Rule	Example
As an image between two paragraphs	1. Click into the Harbor web UI  2. Click on your project.

For markdown formatting for links, see Links, below.

Proper Nouns, Product, and Tool Names

A proper noun is the name given to something to make it more specific. Examples of proper nouns include company names, product names, and tool names. Proper nouns are always capitalized, unlike common nouns that only get capitalized at the start of a new sentence.

When using product names and tool names that are integral to your topic, always link them to a corresponding external site such as a product/project home page for readers to get additional information. You can also link proper nouns to a specific piece of content like an installation guide for a tool. You can also link to a Git repo or piece of code that is pertinent to the context.

Rule	Example
Link proper nouns such as product names to an external website.	[Apache Geode](https://geode.apache.org) provides many Statistics for monitoring the Distributed System including:

Markdown Reference

A good markdown reference can be found here. For Hugo-specific short codes and references, see here.