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