Content best practices
|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.
||Utilize the Admin API.
||Use the Admin API.
|Don’t use Latin phrases
||For example, …
||That is, …
|Avoid generic prounouns
||Once you have added the inputs section, …
||Once you have added this, …
|Don’t use displays
||In the blank that appears, do the thing.
||In the blank that displays, 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.
Follow the user interface(UI). If a term is capitalized in the UI, it should be capitalized in the documentation.
Capitalize the following Kong-specific terms:
- Kong Konnect (Kong Konnect for first mention, Konnect after)
- Kong Gateway
- Kong Mesh (Kong Mesh for first mention, Mesh after)
- Dev Portal
Do not capitalize the following generic terms:
- control plane
- data plane
- hybrid mode
- Separate commands from output.
- Include properly formatted code comments.
- For long commands, split the code block into separate lines to avoid horizontal scrolling.
- Never have more than one command in a block/example.
- Always set a language for codeblocks, for example, bash.
List of supported languages
Inline code formatting
- Use SVGs whenever possible, otherwise use PNGs.
- Limit image file size to ~2MB.
- Do not use shadows.
User Interface text
Reference style guides