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 playbook 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. 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.
Write your content in GitHub-Flavored Markdown. We recommend that you use Visual Studio Code, and set up Visual Studio Code following our [Visual Studio Code Quick Tips]https://info.citrite.net/display/EngSharedSvcs/Visual+Studio+Code+Quick+Tips. You can skip the step to install the Acrolinx plug-in. Acrolinx requires a named user license, so it is available only to the product documentation team.
We recommend installing the markdown validator. If the validator detects deviations from our markdown spec, you cannot commit your changes until those deviations are addressed.
How to 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.
Code samples, inline commands, and output examples
There are three 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. “Retention periods can be adjusted by using the `set-MonitorConfiguration` cmdlet.” Renders as: “Retention periods can be adjusted by using the
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. For example,
set-MonitorConfiguration \` renders as:
Output examples are denoted with indenting. Indent each line with 4 spaces to denote a block of example output.
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 >**Note/Tip/Warning/Important:** \ > \ >text of alert goes here.
Include the colon (:) inside the double-asterisks. The colon is required after the alert type. This markdown renders as:
Text of alert goes here.
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.
To create a table, format as follows:
| Header 1 | Header 2 | Header 3| \ |— |—|—| \ |cell 1 | cell 2 | cell 3| \ |cell 4 | cell 5 | cell 6|
The preceding markdown renders like this:
|Header 1||Header 2||Header 3|
|cell 1||cell 2||cell 3|
|cell 4||cell 5||cell 6|
Style Guide and Quality Standards
All submissions are edited for compliance with the [Citrix Writing Style Guidelines]https://citrixbrand.imagerelay.com/share/758829b0fe0f4ef18bf897e52af734a7, [Citrix Terminology]https://citrix-terminology.knack.com/terminology, and the Microsoft Manual of Style, 4th Edition.
We use an automated editing tool, Acrolinx, to identify issues and to correct them. When you submit your content for publication, one of our leads or managers checks the submission using Acrolinx. 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.
Our readers love images, so include as many as you need to get your message across. All images must be placed in the /media folder of the advanced concepts repo. Our build looks for all images in that folder, so if your images are somewhere else, the build does not pick them up.
- Use PNG format for images.
- Maximum image width is 600 px
- Maximum image size is 500 KB
- Follow the file naming standards provided in this article. That makes it easier to find your images and it makes it easier for others to know what they are.
File Naming Standards
- The file name ends up being the last part of the URL. Think how it will appear in search results pages.
- Use whole words only.
- Separate words with hyphens. Do not use underscores.
- Do not include stopwords such as and, of, or, for, the, etc.
- Do not repeat words that will already appear in the URL. For example, if you are in the sharefile/installation folder, it’s not necessary to name the topic “install-sharefile-separate-use-case.md”
- Make the file name human-readable.
Tips for avoiding repeated editing cycles
- Keep your sentences short–28 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”. (The actual quotations are NSFW.)