Docs: Additions to style guide - placeholders, seealso::, Diátaxis and new word list entry #9840

benjaoming · 2022-12-22T18:53:51Z

CC: @ericholscher these were the 3 things I remember from recent conversations.

Please feel free to suggest more things 👍

📚 Documentation previews 📚

User's documentation (docs): https://docs--9840.org.readthedocs.build/en/9840/

Developer's documentation (dev): https://dev--9840.org.readthedocs.build/en/9840/

…iátaxis checklist from GDocs (with few changes)

humitos · 2022-12-22T19:12:42Z

If you liked my suggestion about com/org differentiation on a note, we could add it here as well

benjaoming · 2022-12-22T19:28:53Z

@humitos I meant to maybe add something about substitutions like |com_brand| and |org_brand| but can you reference the suggestion?

ericholscher

Some good first steps here, had a couple additions and one question.

ericholscher · 2022-12-22T22:26:28Z

docs/dev/style-guide.rst

@@ -43,6 +43,10 @@ Content
  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 <http://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html>`__.
+* Use ``<abstract concept>`` and ``<variable>`` as placeholders in code and URLs. For instance:


I was thinking $variable to differentiate them?

Yes! So on that note, would you prefer $variable and that the example is https://$slug.readthedocs.io ?

Also, the sh interpolation syntax is nice as it give variable boundaries:

https://${slug}.readthedocs.io

I think that I prefer just one notation and that it's <variable name> and <abstract concept>. It's because I have a hard time coming up with examples from our documentation of referenced variable names that are 100% bound and not actually also an abstract concept that we introduced in the docs.

So even if we say https://$slug.readthedocs.io or https://${slug}.readthedocs.io, there actually doesn't exist a real variable called slug but just a concept from the text. So this might as well be <slug> and no distinction.

I think that seems reasonable, especially since we're using $ variables to actually be explicit vars in places in the application (eg;. $rest in redirects). So probably better to preserve them for that.

docs/dev/style-guide.rst

Co-authored-by: Eric Holscher <[email protected]>

humitos · 2022-12-24T14:32:13Z

@benjaoming

I meant to maybe add something about substitutions like |com_brand| and |org_brand| but can you reference the suggestion?

readthedocs.org/docs/user/guides/subprojects.rst

Lines 25 to 32 in d8f5282

    
           .. note:: 
        
              |org_brand| 
        
                 You need to be *maintainer* of a subproject in order to choose it from your main project. 
        
              |com_brand| 
        
                 You need to have *admin access* to the subproject in order to choose it from your main project.

The version diataxis/main is broken on Read the Docs, so I cannot link to the rendered version, but it would appear at https://docs.readthedocs.io/en/diataxis-main/subprojects.html#adding-a-subproject once it builds properly.

…yleguide-updates

… we want to use without a strict formulation

…s.org into styleguide-updates

ericholscher

Header changes look good 👍

benjaoming · 2023-01-11T18:52:11Z

docs/dev/style-guide.rst


 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 provider`` for generic references to GitHub/Bitbucket/GitLab/Gitea etc.
+  We avoid "host" and "platform" because they are slightly more ambiguous.


Better suggestions are most welcome 🙏

I should definitely note that they are called "Services" in the dashboard:

Yea, we also call them integrations in some places too I think? It would be good to be explicit when we're talking about Git-specific hosts that are actually used for code & auth, so I think Git provider is fine? Though provider is a bit abstract as well, tbh, but so are host & platform 🤷

As you also noted in the PR adding texts to the Dashboard UI of "Connected Services", we would want to keep changes to the current Dashboard minimal. In the upcoming Dashboard frontend, we will hopefully recall our terminology and find it natural to add some more tweaks both in the Dashboard and in the documentation. The future version of the documentation will also be less complicated to impose changes to - I feel somewhat confident about that 🤞

docs/dev/style-guide.rst

ericholscher

These changes are great. A couple nits, but I think it's ready to merge.

ericholscher · 2023-01-12T21:43:49Z

docs/dev/style-guide.rst

@@ -43,6 +43,10 @@ Content
  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 <http://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html>`__.
+* Use ``<abstract concept>`` and ``<variable>`` as placeholders in code and URLs. For instance:


I think that seems reasonable, especially since we're using $ variables to actually be explicit vars in places in the application (eg;. $rest in redirects). So probably better to preserve them for that.

ericholscher · 2023-01-12T21:45:49Z

docs/dev/style-guide.rst


 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 provider`` for generic references to GitHub/Bitbucket/GitLab/Gitea etc.
+  We avoid "host" and "platform" because they are slightly more ambiguous.


Yea, we also call them integrations in some places too I think? It would be good to be explicit when we're talking about Git-specific hosts that are actually used for code & auth, so I think Git provider is fine? Though provider is a bit abstract as well, tbh, but so are host & platform 🤷

ericholscher · 2023-01-12T21:46:03Z

docs/dev/style-guide.rst

-* ``Git`` should be upper case, except when referring to the command, when it should be written as `:program:\`git\``.
+* ``Git`` should be upper case. Except when referring to the :program:`git` command, then it should be written as `:program:\`git\``.
+
+Substitutions


This is great 💯

docs/dev/style-guide.rst

Co-authored-by: Eric Holscher <[email protected]>

benjaoming · 2023-01-12T22:06:48Z

I hope that it's fine merging this based on @ericholscher's feedback. I don't have too many worries here, but please feel welcome to ping me back with additional inputs to these changes 👍

Propose something about placeholders, seealso:: references and move D…

161cb88

…iátaxis checklist from GDocs (with few changes)

benjaoming requested a review from a team as a code owner December 22, 2022 18:53

benjaoming requested a review from agjohnson December 22, 2022 18:53

auto-assign bot assigned benjaoming Dec 22, 2022

benjaoming added 2 commits December 22, 2022 19:54

swap . with :

00d5697

sembr a few things

7ccd6eb

benjaoming mentioned this pull request Dec 22, 2022

Docs: Split Traffic Analytics to a How-to guide and a Feature entry (Diátaxis) #9677

Merged

ericholscher reviewed Dec 22, 2022

View reviewed changes

Apply suggestions from code review @ericholscher

7447543

Co-authored-by: Eric Holscher <[email protected]>

benjaoming added 3 commits January 3, 2023 23:28

Merge branch 'main' of github.com:readthedocs/readthedocs.org into st…

9075733

…yleguide-updates

Update heading notation in style guide, add a section to suggest what…

d975ae9

… we want to use without a strict formulation

Merge branch 'styleguide-updates' of github.com:benjaoming/readthedoc…

e582cc8

…s.org into styleguide-updates

ericholscher approved these changes Jan 3, 2023

View reviewed changes

Use cross-references to exemplify..... cross-references!

9181f0c

benjaoming changed the title ~~Docs: Additions to style guide - placeholders, seealso:: and Diátaxis~~ Docs: Additions to style guide - placeholders, seealso::, Diátaxis and new word list entry Jan 4, 2023

benjaoming mentioned this pull request Jan 4, 2023

Docs: Relabel and move explanation and how-tos around OAuth (Diátaxis) #9834

Merged

1 task

Add proposal for using "Git provider"

b7e3827

benjaoming commented Jan 11, 2023

View reviewed changes

benjaoming added 2 commits January 11, 2023 20:52

Add substitutions subsection

9a27fc9

Not dash, make it a sentence (otherwise we can use a definition list)

8733c34

benjaoming force-pushed the styleguide-updates branch 4 times, most recently from df4686e to e7abad7 Compare January 11, 2023 20:52

Add git providers substitution pattern (correcting PGP sig)

2bc794e

benjaoming force-pushed the styleguide-updates branch from e7abad7 to 2bc794e Compare January 11, 2023 20:54

benjaoming commented Jan 12, 2023

View reviewed changes

docs/dev/style-guide.rst Outdated Show resolved Hide resolved

Fix a typo - when=>then

273abf7

benjaoming mentioned this pull request Jan 12, 2023

UI updates to Connected Accounts #9891

Merged

benjaoming requested a review from ericholscher January 12, 2023 20:40

ericholscher approved these changes Jan 12, 2023

View reviewed changes

Apply suggestions from code review @ericholscher

b913829

Co-authored-by: Eric Holscher <[email protected]>

Add section "Differentiating .org and .com" from @humitos' request

8060351

benjaoming merged commit 3ae0dc4 into readthedocs:main Jan 13, 2023

benjaoming deleted the styleguide-updates branch January 13, 2023 10:16

Uh oh!

Docs: Additions to style guide - placeholders, seealso::, Diátaxis and new word list entry #9840

Docs: Additions to style guide - placeholders, seealso::, Diátaxis and new word list entry #9840

Uh oh!

Conversation

benjaoming commented Dec 22, 2022 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

humitos commented Dec 22, 2022

Uh oh!

benjaoming commented Dec 22, 2022

Uh oh!

ericholscher left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

agjohnson Dec 22, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

humitos commented Dec 24, 2022

Uh oh!

ericholscher left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ericholscher left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

benjaoming commented Jan 12, 2023

Uh oh!

Uh oh!

benjaoming commented Dec 22, 2022 •

edited by github-actions bot

Loading

agjohnson Dec 22, 2022 •

edited

Loading