Documentation style

WARNING: You are looking at unreleased Cilium documentation.
Please use the official rendered version released here:
https://docs.cilium.io

      WARNING: You are looking at unreleased Cilium documentation.
      Please use the official rendered version released here:
      https://docs.cilium.io

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`_

- 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.

- The implementation of gateway API
- To create a gateway object, ...

When showing configuration file contents, use the ``literalinclude`` directive
to reference files that exist in the repository (typically in the ``examples/``
directory). If the file does not yet exist in the repository, consider adding it
to the ``examples/`` directory first. This approach ensures the documentation
stays synchronized with the actual file and avoids drift between documentation
and code.

Follow this recommended pattern:

#. Describe to the user how a task could be achieved with the following
   configuration.

#. Use ``literalinclude`` to include the actual file contents.

#. Explain what the configuration means, including the meaning of key settings.

#. Provide a direct command that users can copy and paste to apply the
   configuration.

When providing commands that reference repository files, use the ``|SCM_WEB|``
substitution reference. This ensures the URL points to the correct version
(branch/tag) of the file, matching the documentation version the user is reading.
See the earlier section on `substitution references`_ for details.

Example:

.. code-block:: rst

  To configure feature X, create a file with the following contents:

  .. literalinclude:: ../../examples/kubernetes/feature-x.yaml
      :language: yaml

  This configuration enables feature X by setting:

  - ``enableFeatureX: true``: Activates the feature
  - ``featureXMode: advanced``: Uses advanced mode for better performance

  Apply the configuration with:

  .. parsed-literal::

      $ kubectl apply -f \ |SCM_WEB|\/examples/kubernetes/feature-x.yaml

Using templates with variable substitution
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For configuration files that require user-specific values (cluster names, IDs,
regions), use template files with variable substitution instead of asking users
to manually edit files. This approach reduces errors by controlling exactly what
gets written and maintains the copy-paste testing workflow that maintainers rely
on for debugging.

Store the template file in the ``examples/`` directory with a ``.tmpl`` extension
and use ``envsubst`` to substitute variables.

Example:

.. code-block:: rst

  Create the cluster configuration file:

  .. code-block:: parsed-literal

     export NAME="$(whoami)-$RANDOM"
     curl -L \ |SCM_WEB|\/examples/kubernetes/eks-config.tmpl \\
     | envsubst > eks-config.yaml

  The template contains:

  .. literalinclude:: ../../examples/kubernetes/eks-config.tmpl
      :language: yaml

  The ``${NAME}`` variable will be substituted with your cluster name.

  Create the cluster:

  .. code-block:: shell-session

     $ eksctl create cluster -f eks-config.yaml

This pattern ensures that:

- Maintainers can copy-paste commands sequentially to reproduce user issues
- Variables are controlled rather than manually typed, reducing errors
- Template files are version-controlled and stay synchronized with documentation
- Failures are systematic (template issue) rather than random (user typos)

Links
-----

- Avoid using `embedded URIs`_ (```... <...>`__``), which make the document
  harder to read when looking at the source code of the documentation. Prefer
  to use `block-level hyperlink targets`_ (where the URI is not written
  directly in the sentence in the |RST| file, below the paragraph).

  Prefer:

  .. code-block:: rst

    See the `documentation for Cilium`_.

    Here is another link to `the same documentation <cilium documentation>`_.

    .. _documentation for Cilium:
    .. _cilium documentation: https://docs.cilium.io/en/latest/

  Avoid:

  .. code-block:: rst

    See the `documentation for Cilium <https://docs.cilium.io/en/latest/>`__.

- If using embedded URIs, use anonymous hyperlinks (```... <...>`__`` with two
  underscores, see the documentation for `embedded URIs`_) instead of named
  references (```... <...>`_``, note the single underscore).

  Prefer (but see previous item):

  .. code-block:: rst

    See the `documentation for Cilium <https://docs.cilium.io/en/latest/>`__.

  Avoid:

  .. code-block:: rst

    See the `documentation for Cilium <https://docs.cilium.io/en/latest/>`_.

.. _embedded URIs: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases
.. _block-level hyperlink targets: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets

Lists
-----

- Left-align the body of a list item with the text on the first line, after the 
  item symbol.

  Prefer:

  .. code-block:: rst

    - The text in this item
      wraps of several lines,
      with consistent indentation.

  Avoid:

  .. code-block:: rst

    - 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.

  Prefer:

  .. code-block:: rst

    #. First item
    #. Second item

  Avoid:

  .. code-block:: rst

    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.

  Prefer:

  .. code-block:: rst

    - This is one list item
    - This is another list item

  Avoid:

  .. code-block:: rst

    - This is one list item, period. We use punctuation.
    - This list item should have a period too, but doesn't

Callouts
--------

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:

.. parsed-literal::

    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:

.. parsed-literal::

    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.

Roles
-----

- We have a dedicated role for referencing Cilium GitHub issues, to reference
  them in a consistent fashion. Use it when relevant.

  Prefer:

  .. code-block:: rst

    See :gh-issue:`1234`.

  Avoid:

  .. code-block:: rst

    See `this GitHub issue <https://github.com/cilium/cilium/issues/1234>`__.

Common pitfalls
---------------

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
~~~~~~~~~~~~~~~~

Prefer::

    Enable the flag.

Avoid::

    Ensure the flag is enabled.

Use present tense
~~~~~~~~~~~~~~~~~

Prefer::

    The service returns a response code.

Avoid::

    The service will return a response code.

Address the user as "you", not "we"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Prefer::

    You can specify values to filter tags.

Avoid::

    We'll specify this value to filter tags.

Use plain, direct language
~~~~~~~~~~~~~~~~~~~~~~~~~~

Prefer::

    Always configure the bundle explicitly in production environments.

Avoid::

    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".

Prefer::

    The following example
    To assist this process,

Avoid::

    The example below
    To give this process a boost,

Define abbreviations
~~~~~~~~~~~~~~~~~~~~

Define abbreviations when you first use them on a page.

Prefer::

    Certificate authority (CA)

Avoid::

    CA

Don't use Latin abbreviations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Prefer::

    - For example,
    - In other words,
    - by following the ...
    - and others

Avoid::

    - e.g.
    - i.e.
    - via
    - etc.

Spell words fully
~~~~~~~~~~~~~~~~~

Prefer::

    and

Avoid::

    &

.. _Kubernetes style guide: https://kubernetes.io/docs/contribute/style/style-guide/
.. _content best practices: https://kubernetes.io/docs/contribute/style/style-guide/#content-best-practices

Specific language
-----------------

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:

1. Indirect language assumes too much clarity on the part of the writer and too
   much understanding on the part of the reader.

2. Specific language is easier to review and easier to localize.

Words like "this" and "it" are indirect references. For example:

.. code-block:: rst

  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:

.. code-block:: rst

  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.

Prefer::

    Set the annotation value to remote.

Avoid::

    Set it to remote.