Content best practices
|Use US English (not British English)
||The response should look like…
||The response shall look like…
||In the previous section, you learned…
||In the previous section, you learnt…
|Use present tense
command starts a proxy.
command will start a proxy.
|Use active voice
||You can explore the API using a browser.
||The API can be explored using a browser.
||The YAML file specifies the replica count.
||The replica count is specified in the YAML file.
|Use conversational tone
||Run the program.
||Execute the program.
||Use the Admin API.
||Utilize the Admin API.
|Don’t use Latin phrases
||For example, …
||That is, …
|Avoid generic pronouns
||Once you have added the inputs section, …
||Once you have added this, …
|Don’t use displays or appears
||Do the thing.
||In the blank that appears, do the thing.
|Use descriptive headings
||Improve Vitals performance with InfluxDB
||Query frequency and precision
|Use sentence case for headings
||Understanding traffic flow in Kong Gateway
||Understanding Traffic Flow in Kong Gateway
- Do not stack admonitions, in other words, list several admonitions one after the other.
Admonitions should be carefully selected, called-out text.
- Admonition types:
- Note: Information concerning behavior that would not be expected, but won’t break anything if it’s not followed.
- Warning: Information necessary to avoid breaking something or losing data.
- Important: Information that the reader really needs to pay attention to, otherwise things won’t work.
For more information about formatting admonitions see markdown-rules.
- Commas and periods always go inside quotation marks, and colons and semicolons (dashes as well) go outside.
- For example: “There was a storm last night,” Paul said.
Use single curly braces, all caps text, and underscores between words.
In codeblocks, use editable placeholders
where you want a user to enter their own value.
Follow the user interface (UI). If a term is capitalized in the UI, it should be
capitalized in the documentation.
See Word Choice.
- Separate commands from output.
- Include properly formatted code comments.
- For long commands, split the code block into separate lines with
to avoid horizontal scrolling.
- Never have more than one command in a block/example.
- Set a language for codeblocks, for example, bash, to enable syntax highlighting.
- Do NOT use the command prompt marker ($) in code snippets.
Inline code formatting
- Enclose sample code with single backticks.
For example: `sudo yum install /path/to/package.rpm`
- Add files to the corresponding product folder by navigating in the repo from app > assets > images > docs.
- When naming/titling image files, use lowercase letters and dashes only.
- Use SVGs whenever possible, otherwise use PNGs.
- Limit image file size to ~2MB.
- Compress and resize images before adding them to the site.
- Do not use shadows.
- Borders can be added to screenshots only
- Add an
alt attribute and detailed description of the image.
- Do not use GIFs, as they are not accessible and reduce page performance.
- Don’t use link titles like “Read more” and “Click here”. Instead, write descriptive titles that properly detail what content is accessible by clicking the link.
- If the linked content is a larger area like a panel, add a
title attribute that describes the linked content to the
Reference style guides