docs/style/writing.rst

.. _docs-pw-style-writing:

===================
Writing style guide
===================
.. inclusive-language: disable
.. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText
.. _Sphinx: https://www.sphinx-doc.org/en/master/
.. inclusive-language: enable

This style guide explains how you should style written content that's published
on ``pigweed.dev``.

.. _docs-pw-style-writing-overview:

--------
Overview
--------

.. _docs-pw-style-writing-scope:

Scope
=====
This style guide applies to all written content that's published to
``pigweed.dev``.

.. _docs-pw-style-writing-other:

Other documentation-related style guides
========================================
This style guide is narrowly focused on writing conventions such as how to
capitalize a document title. See :ref:`docs-contrib-docs` for other aspects
of Pigweed's documentation.

.. _docs-pw-style-writing-usage:

Usage
=====
.. _Google developer documentation style guide: https://developers.google.com/style
.. _create an issue: https://pwbug.dev

1. Check if this writing style guide answers your style question.
2. If you don't find an answer in this guide, check the
   `Google developer documentation style guide`_ (GDDSG). If the GDDSG answers
   your question, use that answer.
3. If neither this guide nor the GDDSG answers your question, `create an issue`_
   in the Pigweed tracker. The answer will either get added to this guide or to
   the GDDSG.

.. note::

   The GDDSG is the "base class" of Pigweed's writing style. The writing style
   guide you're currently looking at is the "derived class" that can override
   the base class as needed. Overrides must have very strong rationale.

.. _docs-pw-style-writing-caps:

--------------
Capitalization
--------------

.. _docs-pw-style-writing-caps-headings:

Titles and section headings
===========================
.. _Capitalization in titles and headings: https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings

Use sentence case. See `Capitalization in titles and headings`_.