doc: enhance accessibility guidelines in documentation

Add accessibility guidelines to the documentation guidelines

Signed-off-by: Benjamin Cabé <[email protected]>

Author: kartben

doc/contribute/documentation/guidelines.rst

@@ -54,6 +54,8 @@ the first non-white space in the preceding line.  For example::
 
 Refer to the Zephyr :ref:`coding_style` for additional requirements.
 
+.. _headings:
+
 Headings
 ========
 
@@ -1301,6 +1303,99 @@ Boards
       produce a complete table. If disabled, a warning message will be shown instead of the runners
       tables.
 
+Accessibilty Guidelines
+***********************
+
+Accessibility is an important aspect of documentation, ensuring that all users, including those with
+disabilities, can access and understand the content.
+
+When writing and maintaining Zephyr Project documentation, please follow these guidelines to improve
+accessibility for everyone.
+
+Images and Figures
+==================
+
+All images and figures must include appropriate alternative text (alt text) to convey the meaning of
+the visual content to users who rely on screen readers or cannot view images.
+
+* Use the ``:alt:`` attribute when including images using the :rst:dir:`image` directive.  Example:
+
+  .. code-block:: rst
+     :emphasize-lines: 2
+
+     .. image:: image/doc-gen-flow.png
+        :alt: Documentation generation process overview
+
+* If the image contains text, ensure that the alt text includes this text verbatim.
+
+* When using the :rst:dir:`figure` directive, which allows for a caption, the ``:alt:`` text is
+  still important. The alt text should describe the image itself, while the caption provides
+  additional context or interpretation. Example:
+
+  .. code-block:: rst
+     :emphasize-lines: 4
+
+     .. figure:: ../../images/arch-diagram.png
+        :alt: High-level overview of Zephyr OS architecture showing layers and components.
+
+        High-level overview of Zephyr OS architecture.
+
+- Avoid using images as the sole method of conveying information that can be explained
+  clearly with text.
+
+.. admonition:: Best Practices for writing alt text
+   :class: tip
+
+   * **Be Accurate and Equivalent**: Present the same essential information as the image.
+   * **Be Succinct**: Convey the core message of the image concisely.
+   * **Avoid Redundancy**: Do not use phrases like "Image of..." or "Picture of..." as screen readers
+     typically announce the element as an image.
+   * **Describe, Don't Interpret**: Stick to describing what is visually present on the image.
+   * **Complex Images**: For charts, diagrams, or other complex visuals, provide a summary in the alt
+     text. If a full understanding requires more detail, consider providing a more detailed
+     description in the surrounding text or as part of the figure caption. Using text-based diagram
+     tools like :ref:`Graphviz <graphviz_diagrams>` can also improve accessibility.
+
+
+Headings and Structure
+======================
+
+Use :ref:`headings <headings>` to structure your document logically. This allows users of assistive
+technologies to understand the document's organization and navigate it efficiently.
+
+Tables
+======
+
+Tables should be used only for tabular data and must be accessible to screen readers.
+
+* Always define headers for rows and columns.
+
+* Use the :rst:dir:`list-table` directive when possible for better responsiveness and accessibility.
+
+* Include a caption for tables where context is not immediately obvious. Example:
+
+  .. code-block:: rst
+     :emphasize-lines: 1
+
+     .. list-table:: GPIO Pin Configuration Options
+        :widths: 15 30
+        :header-rows: 1
+
+        * - Field
+          - Description
+        * - GPIO_INPUT
+          - Configures pin as input
+        * - GPIO_OUTPUT
+          - Configures pin as output
+
+Additional Resources
+====================
+
+For more general guidance on web accessibility you may refer to W3C's
+`Web Content Accessibility Guidelines (WCAG)`_
+
+.. _`Web Content Accessibility Guidelines (WCAG)`: https://www.w3.org/WAI/standards-guidelines/wcag/
+
 References
 **********