Docs: New how-to sublevels (Diátaxis) #10131

benjaoming · 2023-03-08T22:58:49Z

Add new How-to subleves and distribute existing pages
Make nice intro pages
Order pages in each level
Entries are just in 1 location, might wanna add some entries in multiple locations
Add redirects for old administrator/developer/author index pages
Is an index page possible or useful at this stage? Move to separate task
Fix up the tense of how-to guide titles
Use only absolute paths (remove relative paths)

Reflections to consider for review

Writing a lot of similarly-worded texts makes the brain a bit tired, so please feel free to make quick suggestions, no darlings here :)
I don't think these texts are super sensitive, but they shouldn't look bad.
The variation is on purpose! I tried NOT to use a formula for every introduction sentence because it'd make the list very boring to the reader's eye.

I wrote an introduction for the very first sub-level and for "best practice", but for all of the other sub-leves, I didn't see that an introduction paragraph contributed anything... it was better without one. Feature reference is the same.

📚 Documentation previews 📚

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

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

…and create better index pages

benjaoming · 2023-03-09T16:15:50Z

I had hoped that I didn't need to write too much new content here. But a lot of the current how-to guides don't have very straight-forward introduction paragraphs. Some don't even have any :)

…levels and add a few missing introduction paragraphs to some guides

…g list of errors

ericholscher

This is great, I didn't do a full copy edit of all the listings pages, but I do think there's likely ways we can be smarter here, rather than copy/pasting the same strings 2-3 places just to remove a couple words. I'd like to find ways to repeat ourselves less, while also providing a good UX to users.

docs/user/guides/access/index.rst

docs/user/guides/best-practice/index.rst

ericholscher · 2023-03-09T22:33:45Z

docs/user/guides/best-practice/index.rst

+Over the years,
+we have become familiar with a number of methods that work well and which we consider **best practice**.


Suggested change

Over the years,

we have become familiar with a number of methods that work well and which we consider **best practice**.

These guides share best practices that we've learned for managing documentation.

If you need ideas for how to get started in various areas of documentation,

this is a great place.

Can you update the suggestion? I can't quite make out what the intention was with the change.

Not hugely important, just trying to clarify what the content is a bit more. But it's not my best writing, for sure.

docs/user/guides/best-practice/index.rst

ericholscher · 2023-03-09T22:40:42Z

docs/user/guides/content/index.rst

@@ -0,0 +1,82 @@
+How-to guides: content, themes and SEO


This is a weird title, and seems unrelated?

You mean than "content, themes and SEO" is a bad category?

I'd rather represent each of these nouns than the alternatives:

Represent important nouns that the reader will recognize.

Hide everything in an umbrella term like "content" or "writing documentation", I don't really like that.. it's ambiguous.

Split up into separate sub-levels. Not to add more sub-levels at this stage IMO.

But if there's better wording for this, that'd be great!

I just don't understand how these 3 things are related, and why only these things? It's a different style than all the other headings, so we should make it similar.

Perhaps:

Suggested change

How-to guides: content, themes and SEO

How-to guides: Improving user experience

Or something?

The sub-levels were written more with an emphasis on "nouns" :) But yeah, I get that the current version has short-comings

I just don't understand how these 3 things are related, and why only these things?

I think that "Improving user experience" does get close to an understanding of how these things are related.

The real issue is probably that we have a good technical understanding of what we mean by content vs. build and configuration. But we can't know if the reader knows where a "theme" fits in!

Currently the menu looks like this:

We could make a menu label that is like: "Content: Themes, SEO and more..." ?

It's also a bit scoped around "Using your documentation tool on Read the Docs" or "Using Sphinx, MkDocs and other tools".

I've noted to get back to this!

docs/user/guides/index.rst

ericholscher · 2023-03-09T22:42:52Z

docs/user/guides/setup/index.rst

+⏩️ :doc:`Connect your Read the Docs account to your Git provider </guides/connecting-git-account>`
+    Steps to connect an account on |git_providers_or| with your Read the Docs account
+
+⏩️ :doc:`Connect your Git repository automatically </connected-accounts>`
+    Connecting your Read the Docs account to one of the supported Git providers, |git_providers_or|.
+
+⏩️ :doc:`Connect your Git repository manually </guides/git-integrations>`
+    Setting up and connecting your Git repository manually, supports most Git providers with webhooks.


It's really not clear to me how these 3 pages differ, as a reader?

It's the same as before. At least now, there's a sentence accompanying each guide :) I think we should solve it separately in this case.

I don't think we can improve much without restructuring the guides? I could imagine that merging the first 2 guides would be beneficial, since "Connect your Read the Docs account to your Git provider" is a precondition for "Connect your Git repository automatically".

Having 2 guides: "Doing things automatically" vs. "Doing things manually" will be less work for the reader to digest.

I just think users want to do the thing, right? The manual & automatic approaches should presumably be in the same place? I just feel like we broke up our guides in a way that makes them much harder for users to use, and we need to undo that if we're finding it confusing, since users will be even more confused.

I think that the manual and automatic approaches are different howtos because they solve different problems. I'm not totally happy with it, but I think it improved now by adding much clearer scope on what the manual guide is for:

Maybe these titles would work better... gonna leave them as a future task...

"Connecting an automatically imported Git repository"

"Connecting a manually imported Git repository"

docs/user/guides/troubleshooting/index.rst

docs/user/guides/build/index.rst

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

…nks.rst

benjaoming · 2023-03-10T13:31:32Z

@ericholscher thanks for the great review, I went through the input and updated everything. It's ready for another review, I haven't found anything further actionable.

Redirects are ready for removed pages 👍

ericholscher

This looks close to me. I really want to fix the issue where we keep repeating subsets of titles and page intros, but we don't need to solve that now. I do think it's important for longer term maintenance, as those will almost certainly get out of sync, but again, not a blocker here.

docs/dev/style-guide.rst

ericholscher · 2023-03-14T20:49:50Z

docs/dev/style-guide.rst

-  then consider rewriting it or turning it into an internal comment afterwards).
+* Title convention: Use words indicating explanation in the title.
+  Like **Understanding <subject>**, **Dive into <subject>**, **Introduction to <subject>** etc.
+* Introduce the scope in the first paragraph: **“This article introduces ...”**.


benjaoming · 2023-03-15T15:27:21Z

This looks close to me. I really want to fix the issue where we keep repeating subsets of titles and page intros, but we don't need to solve that now. I do think it's important for longer term maintenance, as those will almost certainly get out of sync, but again, not a blocker here.

Does it seem good to open a separate issue on researching what to do? Would be nice to hear from others, so I'm thinking we could open it in this very repo.

a) If there's an existing way to do it: We do it!
b) If it requires to write an extension, we need to decide if its worth it..

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

ericholscher · 2023-03-15T21:38:55Z

Yea, 👍 on opening a follow-up issue.

…dthedocs.org into diataxis/howto-sublevels

benjaoming and others added 2 commits March 8, 2023 20:56

WIP: New how-to sublevel structure

fcc63ff

WIP: New sub-levels introduced, need to order items under each level …

35b566e

…and create better index pages

benjaoming added Improvement Minor improvement to code Needed: documentation Documentation is required labels Mar 8, 2023

benjaoming and others added 2 commits March 9, 2023 11:39

WIP

35985f4

Completed writing actual content for all sub-levels on how-to guides

ef62e00

Fill in best practice, represent a couple of guides in different sub-…

8cac4d6

…levels and add a few missing introduction paragraphs to some guides

benjaoming mentioned this pull request Mar 9, 2023

Docs: Diátaxis refactor - iteration 2 high-level tracking #9747

Closed

31 tasks

benjaoming marked this pull request as ready for review March 9, 2023 16:41

benjaoming requested a review from a team as a code owner March 9, 2023 16:41

benjaoming requested a review from ericholscher March 9, 2023 16:41

auto-assign bot assigned benjaoming Mar 9, 2023

benjaoming added 2 commits March 9, 2023 17:43

tweaking the language

5f89fd1

Title of this page indicates a broad guide, but it's a troubleshootin…

8609b11

…g list of errors

ericholscher reviewed Mar 9, 2023

View reviewed changes

benjaoming and others added 5 commits March 10, 2023 11:35

Update docs/user/guides/access/index.rst

15e29a4

Apply suggestions from @ericholscher's code review

6365675

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

Use consistent "tense" for verb fix the last couple of relative paths

bd956a0

Consolidate style guide with How-to convention

635629f

Refactor user/automatic-redirects.rst -> user/guides/best-practice/li…

85cd71c

…nks.rst

benjaoming requested a review from ericholscher March 10, 2023 13:30

ericholscher approved these changes Mar 14, 2023

View reviewed changes

Apply suggestions from code review

fc27f4a

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

benjaoming mentioned this pull request Mar 16, 2023

Docs: Research solution for reusable page meta data #10157

Closed

benjaoming added 2 commits March 16, 2023 16:24

Update lead paragraph for automatic/manual repo how-tos

4a2490e

Merge branch 'diataxis/howto-sublevels' of github.com:readthedocs/rea…

66d69fc

…dthedocs.org into diataxis/howto-sublevels

benjaoming merged commit 176eb7b into main Mar 16, 2023

benjaoming deleted the diataxis/howto-sublevels branch March 16, 2023 16:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: New how-to sublevels (Diátaxis) #10131

Docs: New how-to sublevels (Diátaxis) #10131

benjaoming commented Mar 8, 2023 •

edited

Loading

benjaoming commented Mar 9, 2023

ericholscher left a comment

ericholscher Mar 9, 2023

benjaoming Mar 10, 2023

ericholscher Mar 14, 2023

ericholscher Mar 9, 2023

benjaoming Mar 10, 2023

benjaoming Mar 10, 2023

ericholscher Mar 14, 2023 •

edited

Loading

benjaoming Mar 15, 2023

benjaoming Mar 16, 2023

ericholscher Mar 9, 2023

benjaoming Mar 10, 2023

ericholscher Mar 14, 2023

benjaoming Mar 16, 2023

benjaoming Mar 16, 2023

benjaoming commented Mar 10, 2023 •

edited

Loading

ericholscher left a comment

ericholscher Mar 14, 2023

benjaoming commented Mar 15, 2023

ericholscher commented Mar 15, 2023

		Over the years,
		we have become familiar with a number of methods that work well and which we consider best practice.

-Over the years,
-we have become familiar with a number of methods that work well and which we consider **best practice**.
+These guides share best practices that we've learned for managing documentation.
+If you need ideas for how to get started in various areas of documentation,
+this is a great place.

	How-to guides: content, themes and SEO
	How-to guides: Improving user experience

Docs: New how-to sublevels (Diátaxis) #10131

Docs: New how-to sublevels (Diátaxis) #10131

Conversation

benjaoming commented Mar 8, 2023 • edited Loading

Reflections to consider for review

benjaoming commented Mar 9, 2023

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher Mar 14, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

benjaoming commented Mar 10, 2023 • edited Loading

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

benjaoming commented Mar 15, 2023

ericholscher commented Mar 15, 2023

benjaoming commented Mar 8, 2023 •

edited

Loading

ericholscher Mar 14, 2023 •

edited

Loading

benjaoming commented Mar 10, 2023 •

edited

Loading