github.com/cilium/cilium@v1.16.2/Documentation/contributing/docs/docsstructure.rst (about)

     1  .. only:: not (epub or latex or html)
     2  
     3      WARNING: You are looking at unreleased Cilium documentation.
     4      Please use the official rendered version released here:
     5      https://docs.cilium.io
     6  
     7  .. _docs_structure_recommendations:
     8  
     9  ******************************************
    10  Recommendations on documentation structure
    11  ******************************************
    12  
    13  This page contains recommendations to help contributors write better
    14  documentation. The goal of better documentation is a better user experience. If
    15  you take only one thing away from this guide, let it be this: don't document
    16  your feature. Instead, **document how your feature guides users on their
    17  journey.**
    18  
    19  Maintaining good information architecture
    20  -----------------------------------------
    21  
    22  When you add, update, or remove documentation, consider how the change affects
    23  the site's `information architecture`_. Information architecture is what shapes
    24  a user's experience and their ability to accomplish their goals with Cilium. If
    25  an addition, change, or removal would significantly alter a user's journey or
    26  prevent their success, make sure to flag the change clearly in :ref:`upgrade
    27  notes <current_release_required_changes>`.
    28  
    29  .. _information architecture: https://www.usability.gov/what-and-why/information-architecture.html
    30  
    31  Adding a new page
    32  -----------------
    33  
    34  When you need to write completely new content, create one or more new pages as
    35  one of the three following types:
    36  
    37  - Concept (no steps, just knowledge)
    38  - Task (how to do one discrete thing)
    39  - Tutorial (how to combine multiple features to accomplish specific goals)
    40  
    41  A *concept* explains some aspect of Cilium. Typically, concept pages don't
    42  include sequences of steps. Instead, they link to tasks or tutorials.
    43  
    44  For an example of a concept page, see :ref:`Routing <Routing>`.
    45  
    46  A *task* shows how to do one discrete thing with Cilium. Task pages give
    47  readers a sequence of steps to perform. A task page can be short or long, but
    48  must remain focused on the task's singular goal. Task pages can blend brief
    49  explanations with the steps to perform, but if you need to provide a lengthy
    50  explanation, write a separate concept and link to it. Link related task and
    51  concept pages to each other.
    52  
    53  For an example of a task page, see :ref:`Migrating a Cluster to Cilium
    54  <cni_migration>`.
    55  
    56  A *tutorial* shows how to accomplish a goal using multiple Cilium features.
    57  Tutorials are flexible: for example, a tutorial page could provide several
    58  discrete sequences of steps to perform, or show how related pieces of code
    59  could interact. Tutorials can blend brief explanations with the steps to
    60  perform, but lengthy explanations should link to related concept topics.
    61  
    62  For an example of a tutorial page, see :ref:`Inspecting Network Flows with the
    63  CLI <hubble_cli>`.
    64  
    65  .. note::
    66  
    67    You may need to add multiple pages to support a new feature. For example, if
    68    a new feature requires an explanation of its underlying ideas, add a concept
    69    page as well as a task page.
    70  
    71  Updating an existing page
    72  -------------------------
    73  
    74  Consider whether you can update an existing page or whether to add a new one.
    75  
    76  If adding or updating content to a page keeps it centered on a single concept
    77  or task, then you can update an existing page. If adding or updating content to
    78  a page expands it to include multiple concepts or tasks, then add new pages for
    79  individual concepts and tasks.
    80  
    81  If you're moving a page and changing its URL, make sure you update every link
    82  to that page in the documentation. Ask on `Cilium Slack`_ (``#sig-docs``) for
    83  someone to set up a HTTP redirection from the old URL to the new one, if
    84  necessary.
    85  
    86  Removing content and entire pages
    87  ---------------------------------
    88  
    89  Removing stale content is a part of maintaining healthy docs.
    90  
    91  Whether you're removing stale content on a page or removing a page altogether,
    92  make sure to consider the impact of removal on a user's journey. Specific
    93  considerations include:
    94  
    95  - Updating any links to removed content
    96  - Ensuring users have clear guidance on what to do next
    97  
    98  .. note::
    99  
   100    Without a clearly defined user journey, evaluation is largely qualitative.
   101    Practice empathy: would someone succeed if they had your skills but not your
   102    context?