Use the active voice. See personal pronouns for guidance on when it is appropriate to use "you" and "your".
- Bad: The files should be added to the directory by the owner.
- Good: The owner should add the files to the directory.
- Bad: To access a network's LDAP services, your computer must first be authenticated.
- Good: To access a network's LDAP services, a server that supports the protocol must first authenticate your computer.
Use proper case for the Kong entity, lowercase for the RBAC Role.
- Invite the Admin using the Organization tab
- The default Roles are super-admin, admin, and read-only
Use proper case.
Use Kong Manager instead.
Use American English throughout Kong documentation.
Always use "and" in content, only use "&" in titles with two items that have always had it or in product names.
All upper case; if referring to an entity, use Services and Routes instead.
Use proper case; abbreviate if the context permits. Only use lowercase (with a hyphen) in code or configuration samples.
- Bad: Options include LDAP Auth and basic auth.
- Good: Options include LDAP Auth and Basic Auth.
- Bad: Ensure that
admin_gui_authis set to basic auth. - Good: Ensure that
admin_gui_authis set tobasic-auth. - Good: Ensure that
admin_gui_auth = basic-auth.
Use bold text for:
- Visible GUI text, e.g., click the Organization tab.
- Usernames or Workspace names, e.g., Gruce or Payments
- Term lists, e.g.,
- bucanneers: 17th-century French hunters who survived on the island of Hispaniola by hunting wild cattle and swine and smoking the meat in a wooden frame called a boucane, whence boucaniers. Many became pirates after being driven off the island by the Spanish.
- pirates: people who commit unsanctioned theft by use of a vessel.
- privateers: civilian sailors licensed to attack an enemy of their country at war and keep the plunder on condition of paying their government a certain percentage. Many would turn to piracy when the war officially ended.
- Emphasis when changing context for a command, like switching to a new
workspace or user, e.g.,
Log in as a super admin and move from the default workspace to Payments. Then check the Admins page to see if Gruce has accepted the invitation.
Do not use bold text for headings or anything that should be formatted with in-line code.
Do not use "click on"; specify what is being clicked.
- Bad: Click on Admins.
- Bad: Look for one that says "Admins" and click.
- Good: Click the Admins button.
Use a code block to indicate multiple lines of code or an example command. For one line, see in-line code.
To write a code block, add 3 backticks (```) to the top and bottom of the
block.
$ kong migrations bootstrap
If a specific language is used, specify it. For example, this block:
```javascript
let password = 'hunter2' // use 'quotes' for strings
alert(`Your password is ${password}`) // use `ticks` for template literals
```
produces the contents with JavaScript's syntax highlighting:
let password = 'hunter2' // use 'quotes' for strings
alert(`Your password is ${password}`) // use `ticks` for template literalsDo not write as "CURL" or "curl".
Indicates an inexhaustive list of examples, so "etc." is redundant. Use "i.e." if offering a clarification, rather than an example. Following the Chicago Manual, follow "e.g." with a comma before the example.
- Bad: Users may select a role, e.g. admin, read-only, etc.
- Good: Users may select a role, e.g., admin, read-only.
- Bad: The Role with the most RBAC permissions, e.g. the super admin.
- Good: The Role with the most RBAC permissions, i.e., the super admin.
Indicates an incomplete thought or omission, not a pause thought; see em-dash.
- Bad: Click "Garth-Stuff"... or more interestingly, the user named "KongOps".
- Good: The error message will start, "Unable to complete request..."
Indicates a pause or emphatic break in a sentence; it is not a hyphen and has no surrounding space.
- Bad: The admin Role allows a user access to all endpoints... except for RBAC Permissions.
- Bad: The admin Role allows a user access to all endpoints - except for RBAC Permissions.
- Good: The admin Role allows a user access to all endpoints—except for RBAC Permissions.
For explanatory sections, specify the value of the content, then provide clarification and examples. Avoid starting sections with casual or redundant information, e.g., "In this section, you'll learn how to do X." For example, in a section titled "Negotiation with Pirates":
- Bad: In this section, you will learn the reason for negotiating with pirates. Pirates may seem scary, but they can be reasoned with. Just match their body language and offer them some rum. From there, negotiation is self-explanatory. Now you know how to negotiate with pirates.
- Good: Although pirates do not abide by the law, it is possible to come to a reasonable compromise with them. Their goal is financial gain, not a fight, and many of them were once merchant sailors. If it is not possible to deter them, it is best to maintain a friendly disposition. For the safety of your crew, keep their motivations in mind at all times during negotiation.
For section headings, use ##. For subsections, use ###. Do not use # for
a title, as it will nest the table of contents.
## Section 1
### Subsection 1.a
## Section 2
### Subsection 2.a
### Subsection 2.b
Any section of documentation that is a guide involving multiple steps should have the following:
- A title starting with "How to"
- Bad: Creating New Admins in a Workspace
- Good: How to Create New Admins in a Workspace
- Numbered steps, 2 to 5 in length; anything with more than 5 steps can be broken down into separate guides
- Oriented towards a goal, not teaching; each step should be minimal and
straightforward
- detailed explanation may go in a separate section below the how-to guide, but should not interrupt it
- important tags that prevent an undesired outcome may go at the bottom of a step, but should not be overused
- Each step in a how-to guide should be identical to its TL;DR version—if any content is inessential, it can go into a blog post or a more appropriate section
Do not write "httpie" or "HTTPIE".
See e.g.; should only be used to specify a case, not offer possible examples.
Included images should be 1200px wide. Introduce image concept before showing the image, not after. See: screenshots and videos
Use in-line code formatting for:
- Command names, e.g.,
kong start - Package names, e.g.,
luarocks - Optional commands
- Variable names, e.g.
KONG_PASSWORD - Configuration properties and values, e.g.,
admin_gui_authldap-auth-advancedadmin_gui_auth = ldap-auth-advanced
- File names and paths, like
~/.ssh/authorized_keys - Example URLs that are not active links, like
http://example.com - Ports, like
:3000 - Key presses, which should be in ALL CAPS and use a plus symbol,
+, if keys need to be pressed simultaneously, such asENTERorCTRL+C
For multiple lines of code or an example command, use a code block.
Do not use in-line formatting for anything that should be in bold text.
Do not add indentation unless it's functionally relevant, e.g., in YAML files, sub-bulleted lists.
Unnecessary indentation can potentially conflict with styling that CSS applies to the markdown. In general, keep the markdown free of styling as much as possible, outside of what's already documented here for things like inline code, entities, etc.
Use proper case.
Use Admin or admin (see Admin, admin) instead.
Use Kong instead—except in pre-1.0 versions, e.g. "Kong CE 0.12".
Use Dev Portal instead, not "Developer Portal".
Use proper case.
Use Kong Enterprise instead—except in pre-34 versions, e.g. "Kong EE 0.32".
Use proper case.
Joined as a noun/modifier, separated as a phrasal verb; added prepositions are also separated.
- To see the dashboard, log in as an admin.
- Log in to the app.
- Reset your password at the login page.
Write all numbers as digits (including 1–9). Ranges should use an en-dash (–) instead of "to" or "through".
- Bad: If a user has more than five bins, provide nine to 23 blocks.
- Good: If a user has more than 5 bins, provide 9–23 blocks.
- Bad: This guide assumes steps one through three from the previous guide.
- Good: This guides assumes steps 1–3 from the previous guide.
See active voice.
Avoid "you" and "we" in favor of the specific role performing the task or the imperative mood, but do not use the passive voice if "you" would be simpler.
- Bad: We will start by creating credentials for you.
- Good: To start, create credentials for the super admin.
- Bad: Log in with the password that was set during migrations.
- Good: Log in with the password you set during migrations.
Use proper case.
Use proper case.
Use proper case, introduce full phrase only once per section, use abbreviation after.
Use proper case.
Screenshots should be 1200px wide, do not include browser tool bars, title bars, url bars etc.
For safety, clarity, and sanity.
Joined as a noun/modifier, separated as a phrasal verb.
- A protocol is required to set up a service.
- To learn more, visit the account setup guide.
Use proper case.
Use one space after a period, not two.
Use lowercase, hyphen as a compound modifier. Note that an Admin is a Kong entity, whereas admin and super admin refer to particular Roles assigned to an Admin, or users with those particular Roles.
- Invite a super admin.
- An Admin account may invite others if it has super-admin Permissions.
Maintain the case, format with bold text.
-
Click Admins in the sidebar.
-
Use the Add Role button.
Prepositions and articles are lower case, everything else is proper case.
- Create RBAC Roles for an Admin in the New Workspace.
Has a specific meaning, "to use what is available"; it should not be used a fancy synonym for "use".
- Bad: The Admin may utilize the feature to observe traffic.
- Good: The Admin may use the feature to observe traffic.
Videos should be less than 30 seconds in length, contain no voice-over narration, and must be approved by a Kong member.
Include videos after the steps covered in the video have been introduced.
Use proper case.
Use proper case.