From 8e64bf3c881d8429b6ea96ef49d9bcf6bd25ef28 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 14 Dec 2022 14:48:32 -0800 Subject: [PATCH 1/8] Break documentation style guide out into its own file. This is the start of a larger style guide that we should have, trying to capture places where we make decisions. --- docs/dev/docs.rst | 33 -------------------------- docs/dev/style-guide.rst | 50 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 33 deletions(-) create mode 100644 docs/dev/style-guide.rst diff --git a/docs/dev/docs.rst b/docs/dev/docs.rst index 899a503432e..2c97b96485f 100644 --- a/docs/dev/docs.rst +++ b/docs/dev/docs.rst @@ -67,36 +67,3 @@ you may want to verify those changes locally before pushing upstream. (.venv) $ RTD_DOCSET=dev make livehtml #. the documents will be available at http://127.0.0.1:4444/ and will rebuild each time you edit and save a file. - -Guidelines ----------- - -Please follow these guidelines when updating our docs. -Let us know if you have any questions or something isn't clear. - -The brand -^^^^^^^^^ - -We are called **Read the Docs**. -The *the* is not capitalized. - -We do however use the acronym **RTD**. - -Titles -^^^^^^ - -For page titles, or Heading1 as they are sometimes called, we use title-case. - -If the page includes multiple sub-headings (H2, H3), -we usually use sentence-case unless the titles include terminology that is supposed to be capitalized. - -Content -^^^^^^^ - -* Do not break the content across multiple lines at 80 characters, - but rather break them on semantic meaning (e.g. periods or commas). - Read more about this `here `_. -* If you are cross-referencing to a different page within our website, - use the ``doc`` role and not a hyperlink. -* If you are cross-referencing to a section within our website, - use the ``ref`` role with the label from the `autosectionlabel extension `__. diff --git a/docs/dev/style-guide.rst b/docs/dev/style-guide.rst new file mode 100644 index 00000000000..8d0318f9297 --- /dev/null +++ b/docs/dev/style-guide.rst @@ -0,0 +1,50 @@ +Documentation Style Guide +========================= + +This document will serve as the canonical place to define how we write documentation at Read the Docs. +The goal is to have a shared understanding of how things are done, +and document the conventions that we follow. + +Let us know if you have any questions or something isn't clear. + +The brand +--------- + +We are called **Read the Docs**. +The ``the`` is not capitalized. + +We do however use the acronym **RTD**. + +Titles +------ + +For page titles we use sentence case. +This means only proper nouns and the first word are capitalized:: + +# Good ✅ +How we handle support on Read the Docs. + +# Bad 🔴 +How we Handle Support on Read the Docs + +If the page includes multiple sub-headings (H2, H3), +we use sentence case there as well. + +Content +------- + +* Do not break the content across multiple lines at 80 characters, + but rather break them on semantic meaning (e.g. periods or commas). + Read more about this `here `_. +* If you are cross-referencing to a different page within our website, + use the ``doc`` role and not a hyperlink. +* If you are cross-referencing to a section within our website, + use the ``ref`` role with the label from the `autosectionlabel extension `__. + +Word List +--------- + +We have a specific way that we write common words: + +* ``open source`` should be lower case. +* ``git`` should be lower case. From f6d14ec1846bc2863177e47aa0822694328fa49e Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 14 Dec 2022 14:50:03 -0800 Subject: [PATCH 2/8] Link to glossary --- docs/dev/style-guide.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/dev/style-guide.rst b/docs/dev/style-guide.rst index 8d0318f9297..dadc9bb615f 100644 --- a/docs/dev/style-guide.rst +++ b/docs/dev/style-guide.rst @@ -33,6 +33,7 @@ we use sentence case there as well. Content ------- +* Use ``:guilabel:`` when referring to an element on the screen. * Do not break the content across multiple lines at 80 characters, but rather break them on semantic meaning (e.g. periods or commas). Read more about this `here `_. @@ -48,3 +49,5 @@ We have a specific way that we write common words: * ``open source`` should be lower case. * ``git`` should be lower case. + +You can also see the :doc:`/glossary` other words that have canonical definitions in our docs. From 40f8389f72819250d4ceaf6d0f25afac596f44af Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 14 Dec 2022 14:51:20 -0800 Subject: [PATCH 3/8] Add to toctree --- docs/dev/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/dev/index.rst b/docs/dev/index.rst index ef7cfb4dfa6..bed5cdd90a0 100644 --- a/docs/dev/index.rst +++ b/docs/dev/index.rst @@ -22,6 +22,7 @@ or taking the open source Read the Docs codebase for your own custom installatio guides/index design docs + style-guide front-end i18n server-side-search From ebe8c80da77d603ae3dea6e631077c56be5a21fb Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 15 Dec 2022 10:52:43 -0800 Subject: [PATCH 4/8] Apply suggestions from code review Co-authored-by: Benjamin Balder Bach --- docs/dev/style-guide.rst | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/dev/style-guide.rst b/docs/dev/style-guide.rst index dadc9bb615f..797d28d8930 100644 --- a/docs/dev/style-guide.rst +++ b/docs/dev/style-guide.rst @@ -33,7 +33,9 @@ we use sentence case there as well. Content ------- -* Use ``:guilabel:`` when referring to an element on the screen. +* Use ``:menuselection:`` when referring to an item or sequence of items in navigation. +* Use ``:guilabel:`` when referring to a visual element on the screen - such as a button, drop down or input field. +* Use ``**bold text**`` when referring to a non-interactive text element, such as a header. * Do not break the content across multiple lines at 80 characters, but rather break them on semantic meaning (e.g. periods or commas). Read more about this `here `_. @@ -50,4 +52,17 @@ We have a specific way that we write common words: * ``open source`` should be lower case. * ``git`` should be lower case. -You can also see the :doc:`/glossary` other words that have canonical definitions in our docs. +Glossary +-------- + +Since the above Word List is for internal reference, +we also maintain a :doc:`/glossary` with terms that have canonical definitions in our docs. +Terms that can otherwise have multiple definitions +*or* have a particular meaning in Read the Docs context +should always be added to the :doc:`/glossary` and referenced using the ``:term:`` role. + +Using a glossary helps us (authors) to have consistent definitions +but even more importantly, +it helps and includes readers by giving them quick and easy access to terms that they may be unfamiliar with. + +Use an external link or Intersphinx reference when a term is clearly defined elsewhere. From 163e086cd63c242bd6ba6d1d2caa765e8a4d0b1c Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 15 Dec 2022 10:53:48 -0800 Subject: [PATCH 5/8] Update docs/dev/style-guide.rst Co-authored-by: Benjamin Balder Bach --- docs/dev/style-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/style-guide.rst b/docs/dev/style-guide.rst index 797d28d8930..895ecdb1b40 100644 --- a/docs/dev/style-guide.rst +++ b/docs/dev/style-guide.rst @@ -49,7 +49,7 @@ Word List We have a specific way that we write common words: -* ``open source`` should be lower case. +* ``open source`` should be lower case, unless you are definitely referring to `OSI's Open Source Definition `. * ``git`` should be lower case. Glossary From 1d6d40561b373a5c17d1f3398e1bd754c246eb90 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 15 Dec 2022 10:54:56 -0800 Subject: [PATCH 6/8] Update style-guide.rst --- docs/dev/style-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/style-guide.rst b/docs/dev/style-guide.rst index 895ecdb1b40..b175ef0addf 100644 --- a/docs/dev/style-guide.rst +++ b/docs/dev/style-guide.rst @@ -50,7 +50,7 @@ Word List We have a specific way that we write common words: * ``open source`` should be lower case, unless you are definitely referring to `OSI's Open Source Definition `. -* ``git`` should be lower case. +* ``Git`` should be upper case, except when referring to the command, when it should be written as `:program:\`git\``. Glossary -------- From 0951928ad6962a8f6ebf8426f35e169b85c70134 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Thu, 15 Dec 2022 13:57:37 -0800 Subject: [PATCH 7/8] Update style-guide.rst --- docs/dev/style-guide.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/dev/style-guide.rst b/docs/dev/style-guide.rst index b175ef0addf..dc33b098fa4 100644 --- a/docs/dev/style-guide.rst +++ b/docs/dev/style-guide.rst @@ -49,6 +49,7 @@ Word List We have a specific way that we write common words: +* ``Git repository`` for the place that stores Git repos. We used to use ``VCS``, but this is deprecated. * ``open source`` should be lower case, unless you are definitely referring to `OSI's Open Source Definition `. * ``Git`` should be upper case, except when referring to the command, when it should be written as `:program:\`git\``. From 4b4c5ffe3261d9741ef8dd06595fe9c059f0f0bf Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 15 Dec 2022 14:52:34 -0800 Subject: [PATCH 8/8] Fix lint --- docs/dev/style-guide.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/dev/style-guide.rst b/docs/dev/style-guide.rst index dc33b098fa4..1cb2462e419 100644 --- a/docs/dev/style-guide.rst +++ b/docs/dev/style-guide.rst @@ -21,11 +21,11 @@ Titles For page titles we use sentence case. This means only proper nouns and the first word are capitalized:: -# Good ✅ -How we handle support on Read the Docs. + # Good ✅ + How we handle support on Read the Docs. -# Bad 🔴 -How we Handle Support on Read the Docs + # Bad 🔴 + How we Handle Support on Read the Docs If the page includes multiple sub-headings (H2, H3), we use sentence case there as well. @@ -49,7 +49,7 @@ Word List We have a specific way that we write common words: -* ``Git repository`` for the place that stores Git repos. We used to use ``VCS``, but this is deprecated. +* ``Git repository`` for the place that stores Git repos. We used to use ``VCS``, but this is deprecated. * ``open source`` should be lower case, unless you are definitely referring to `OSI's Open Source Definition `. * ``Git`` should be upper case, except when referring to the command, when it should be written as `:program:\`git\``. @@ -57,10 +57,10 @@ Glossary -------- Since the above Word List is for internal reference, -we also maintain a :doc:`/glossary` with terms that have canonical definitions in our docs. +we also maintain a :doc:`rtd:glossary` with terms that have canonical definitions in our docs. Terms that can otherwise have multiple definitions *or* have a particular meaning in Read the Docs context -should always be added to the :doc:`/glossary` and referenced using the ``:term:`` role. +should always be added to the :doc:`rtd:glossary` and referenced using the ``:term:`` role. Using a glossary helps us (authors) to have consistent definitions but even more importantly,