Here are some guidelines and best practices for contributing to Cilium’s documentation. They have several objectives:
Ensure that the documentation is rendered in the best possible way (in particular for code blocks).
Make the documentation easy to maintain and extend.
Help keep a consistent style throughout the documentation.
In the end, provide a better experience to users, and help them find the information they need.
See also the documentation for testing for instructions on how to preview documentation changes.
Write in US English. For example, use “prioritize” instead of “prioritise” and “color” instead of “colour”.
Maintain a consistent style with the rest of the documentation when possible, or at least with the rest of the updated page.
Omit hyphens when possible. For example, use “load balancing” instead of “load-balancing”.
Use the following header when adding new files to the Documentation.
.. only:: not (epub or latex or html) WARNING: You are looking at unreleased Cilium documentation. Please use the official rendered version released here: https://docs.cilium.io
One exception is reStructuredText fragments that are supposed to be sourced from other documentation files. Those do not need this header.
Prefer sentence case (capital letter on first word) rather than title case for all headings.
Wrap the lines for long sentences or paragraphs. There is no fixed convention on the length of lines, but targeting a width of about 80 characters should be safe in most circumstances.
Follow the section on capitalization for API objects from the Kubernetes style guide for when to (not) capitalize API objects. In particular:
When you refer specifically to interacting with an API object, use UpperCamelCase, also known as Pascal case.
When you are generally discussing an API object, use sentence-style capitalization
For example, write “Gateway API”, capitalized. Use “Gateway” when writing about an API object as an entity, and “gateway” for a specific instance.
The following examples are correct:
- Gateway API is a subproject of Kubernetes SIG Network. - Cilium is conformant to the Gateway API spec at version X.Y.Z. - In order to expose this service, create a Gateway to hold the listener configuration. - Traffic from the Internet passes through the gateway to get to the backend service. - Now that you have created the "foo" gateway, you need to create some Routes.
But the following examples are incorrect:
- The implementation of gateway API - To create a gateway object, ...
Code snippets and other literal blocks usually fall under one of those three categories:
They contain substitution references (for example:
|SCM_WEB|). In that case, always use the
.. parsed-literaldirective, otherwise the token will not be substituted.
.. parsed-literal:: $ kubectl create -f \ |SCM_WEB|\/examples/minikube/http-sw-app.yaml
.. code-block:: shell-session $ kubectl create -f \ |SCM_WEB|\/examples/minikube/http-sw-app.yaml
If the text is not a code snippet, but just some fragment that should be printed verbatim (for example, the unstructured output of a shell command), use the marker for literal blocks (
See the output in ``dmesg``: :: [ 3389.935842] flen=6 proglen=70 pass=3 image=ffffffffa0069c8f from=tcpdump pid=20583 [ 3389.935847] JIT code: 00000000: 55 48 89 e5 48 83 ec 60 48 89 5d f8 44 8b 4f 68 See more output in ``dmesg``:: [ 3389.935849] JIT code: 00000010: 44 2b 4f 6c 4c 8b 87 d8 00 00 00 be 0c 00 00 00 [ 3389.935850] JIT code: 00000020: e8 1d 94 ff e0 3d 00 08 00 00 75 16 be 17 00 00
See the output in ``dmesg``: .. parsed-literal:: [ 3389.935842] flen=6 proglen=70 pass=3 image=ffffffffa0069c8f from=tcpdump pid=20583 [ 3389.935847] JIT code: 00000000: 55 48 89 e5 48 83 ec 60 48 89 5d f8 44 8b 4f 68
The reason is that because these snippets contain no code, there is no need to mark them as code or parsed literals. The former would tell Sphinx to attempt to apply syntax highlight, the second would tell it to look for reStructuredText markup to parse in the block.
If the text contained code or structured output, use the
.. code-blockdirective. Do not use the
.. codedirective, which is slightly less flexible.
.. code-block:: shell-session $ ls cilium $ cd cilium/
.. parsed-literal:: $ ls cilium $ cd cilium/ .. code-block:: bash $ ls cilium $ cd cilium/ .. code-block:: shell-session ls cilium cd cilium/
.. code-blockdirective should always take a language name as argument, for example:
.. code-block:: yamlor
.. code-block:: shell-session. The use of
bashis possible but should be limited to Bash scripts. For any listing of shell commands, and in particular if the snippet mixes commands and their output, use
shell-session, which will bring the best coloration and may trigger the generation of the
For snippets containing shell commands, in particular if they also contain the
output for those commands, use prompt symbols to prefix the commands. Use
for commands to run as a normal user, and
# for commands to run with
administrator privileges. You may use
sudo as an alternative way to mark
commands to run with privileges.
Left-align the body of a list item with the text on the first line, after the item symbol.
- The text in this item wraps of several lines, with consistent indentation.
- The text in this item wraps on several lines and the indent is not consistent with the first line.
For enumerated lists, prefer auto-numbering with the
#.marker rather than manually numbering the sections.
#. First item #. Second item
1. First item 2. Second item
Be consistent with periods at the end of list items. In general, omit periods from bulleted list items unless the items are complete sentences. But if one list item requires a period, use periods for all items.
- This is one list item - This is another list item
- This is one list item, period. We use punctuation. - This list item should have a period too, but doesn't
Use callouts effectively. For example, use the
.. note:: directive to
highlight information that helps users in a specific context. Do not use it to
avoid refactoring a section or paragraph.
For example, when adding information about a new configuration flag that completes a feature, there is no need to append it as a note, given that it does not require particular attention from the reader. Avoid the following:
Blinking pods are easier to spot in the dark. Use feature flag ``--blinking-pods`` to make new pods blink twice when they launch. If you create blinking pods often, sunglasses may help protect your eyes. .. note:: Use the flag ``--blinking-pods-blink-number`` to change the number of times pods blink on start-up.
Instead, merge the new content with the existing paragraph:
Blinking pods are easier to spot in the dark. Use feature flag ``--blinking-pods`` to make new pods blink when they launch. By default, blinking pods blink twice, but you can use the flag ``--blinking-pods-blink-number`` to specify how many times they blink on start-up. If you create blinking pods often, sunglasses may help protect your eyes.
We have a dedicated role for referencing Cilium GitHub issues, to reference them in a consistent fashion. Use it when relevant.
See `this GitHub issue <https://github.com/cilium/cilium/issues/1234>`__.
There are best practices for writing documentation; follow them. In general, default to the Kubernetes style guide, especially for content best practices. The following subsections cover the most common feedback given for Cilium documentation Pull Requests.
Use active voice
Enable the flag.
Ensure the flag is enabled.
Use present tense
The service returns a response code.
The service will return a response code.
Address the user as “you”, not “we”
You can specify values to filter tags.
We'll specify this value to filter tags.
Use plain, direct language
Always configure the bundle explicitly in production environments.
It is recommended to always configure the bundle explicitly in production environments.
Write for good localization
Assume that what you write will be localized with machine translation. Figures of speech often localize poorly, as do idioms like “above” and “below”.
The following example To assist this process,
The example below To give this process a boost,
Define abbreviations when you first use them on a page.
Certificate authority (CA)
Don’t use Latin abbreviations
- For example, - In other words, - by following the ... - and others
- e.g. - i.e. - via - etc.
Spell words fully
Use specific language. Avoid words like “this” (as a pronoun) and “it” when referring to concepts, actions, or process states. Be as specific as possible, even if specificity seems overly repetitive. This requirement exists for two reasons:
Indirect language assumes too much clarity on the part of the writer and too much understanding on the part of the reader.
Specific language is easier to review and easier to localize.
Words like “this” and “it” are indirect references. For example:
Feature A requires all pods to be painted blue. This means that the Agent must apply its "paint" action to all pods. To achieve this, use the dedicated CLI invocation.
In the preceding paragraph, the word “this” indirectly references both an inferred consequence (“this means”) and a desired goal state (“to achieve this”). Instead, be as specific as possible:
Feature A requires all pods to be painted blue. Consequently, the Agent must apply its "paint" action to all pods. To make the Agent paint all pods blue, use the dedicated CLI invocation.
The following subsections contain more examples.
Use specific wording rather than vague wording
For each core, the Ingester attempts to spawn a worker pool.
For each core, it attempts to spawn a worker pool.
Use specific instructions rather than vague instructions
Set the annotation value to remote.
Set it to remote.