Product Documentation

Contributor Guidelines

Welcome to the product documentation team! We’re delighted that you’re interested in contributing to our site.

Before you start, we’d like to share the guidelines and the rules for contributions.

Our site supports multi-channel output, including HTML, PDF, and screen readers, not to mention that the site design is responsive. Therefore, we’ve tuned the markdown requirements to ensure integrity of the output no matter which output type we’re looking at. We’ve also locked down the markdown spec to ensure build integrity, dependability, and continuous deployment.

Besides the output considerations, we aim for readability. Keep your writing at a 9th or 10th grade (U.S.) reading level. That reading level is the equivalent of a Flesch reading ease score of 60 or higher. This helps our fluent English-language readers to get what they need fast, without having to study. And it alleviates pain for our audience members who don’t read English well, or who prefer another language.

Authoring content in markdown

Write your content in GitHub-Flavored Markdown. Markdown is easy to use and to remember. To get you started, we’re providing a few pointers for getting your article just right. Our markdown spec does not allow raw HTML, even though GitHub-Flavored Markdown does. Do not use raw HTML in your source–stick with markdown. The Mastering Markdown reference is one we find very useful.

Code samples, inline commands, and output examples

There are two ways to mark up code examples and commands:

  • Inline commands in a sentence are offset with single backticks `. For example, if you mention a command in a sentence, you put backticks around the command. The following image shows an inline command in markdown source:

inline source

The following image shows the output that corresponds to the previous image:

inline code

  • Code blocks or code samples are denoted with triple backticks ```. Use triple backticks when you want to make the code block available for the reader to copy and paste. Code blocks must be surrounded by blank lines, as shown in the example image.

The following image shows a sample code block in the source markdown:

code block example code

The following image shows the output that corresponds to the sample code block markdown:

code block rendered

Notes, tips, Warnings, and Important

Use alerts (also called admonitions) sparingly. Think of alerts as shouting.

To include an alert, use > before each line of the alert. Our standard for formatting alerts is to use the word note, tip, warning, or important, depending on the nature of the information we’re communicating. The colon (:) is required after the alert type.

The following image shows an example of an alert formatted in the markdown:

alert source code

This markdown renders as:

alert rendered

Tables

Keep tables simple and use them only for comparisons. To provide lists, use glossary-style entries, which are much friendlier in different output formats, such as mobile devices and screen readers.

Use pipe characters (|) to separate table cells. We’ve found that formatting is more predictable when we use the optional pipe character (|) at the beginning and end of each row.

The following image shows the markdown source for a table:

table source code

The markdown in the preceding image renders like this:

table rendered

Style Guide and Quality Standards

All submissions are edited for compliance with the Citrix Writing Style Guidelines, Citrix Terminology, and the Microsoft Manual of Style, 4th Edition.

We use an automated editing tool to identify issues and to correct them. When you submit your content for publication, one of our leads or managers checks the submission using that editing tool. We make corrections based on Citrix terminology, style, and voice guidelines. Any significant changes (such as long sentences being rewritten) require technical review and verification.

Tips for avoiding repeated editing cycles

  • Keep your sentences short–26 words or fewer.
  • Use only approved and valid Citrix terms.
  • Write in a personal, friendly style. Do not use the style of academic discourse.
  • Write in present tense. For example, “the product reports the result” instead of “the product will report the result.”
  • Make every word count. We get complaints from readers when the writing sounds too “markety”.

Contributor Guidelines