Docs: Relabel and reorganize hosting features as reference (Diátaxis) #9952

benjaoming · 2023-01-26T16:05:21Z

Changes:

New hosting feature overview, using short sentences and references to "read more"
Added additional features that may be understood as hosting
Added link to the general features overview
Organized Sphinx/MkDocs reference as tabs
Added instructions for custom 404s on MkDocs
New level "Built-in content" meant to reflect auto-generated contents that we host - robots.txt, 404s and sitemaps.

TBD: There's some leftovers of explanation and instructions, but those are all so short that they make very little sense in their own how-to guides.

💡 if we have a lot of small things for either Sphinx or MkDocs, we could consider writing how-tos like "The most popular tweaks for Sphinx projects" where we just mention these in a way that can be referenced.

Refs: #9746

📚 Documentation previews 📚

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

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

…rganizing content

ericholscher · 2023-01-30T23:37:52Z

Dropped @agjohnson from Advocacy team reviews for now, so he doesn't get pinged on these.

ericholscher

@benjaoming I started a review here, but this document feels half baked. There's a bunch of broken links, and lots of ways the language could be improved with some simple edits.

Should I be doing a full second edit of this instead of a review? It would be good to clarify that in the PR.

docs/user/hosting.rst

…g into diataxis/split-hosting-features

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

…here

benjaoming · 2023-02-01T13:17:21Z

@ericholscher

Should I be doing a full second edit of this instead of a review? It would be good to clarify that in the PR.

The PR had a lot of restructuring, so I didn't feel comfortable sitting with it for so long without having another pair of eyes. It would be super-nice if you want to go over it for a second edit and just change anything you come across 👍

I wouldn't mind postponing further improvements to later. I can't help but feel that there is something weird about describing Sitemaps and CDN in the same page. But it's possibly better saved for another iteration.

ericholscher · 2023-02-02T00:09:41Z

@benjaoming I started to do a second edit of this content, but the structuring feels weird to me. I think the hosting feature overview is definitely a sales/marketing type page. I don't think it makes sense at the top of a feature page for the actual hosting features.

Perhaps it just doesn't have a good home in this new layout, and the marketing pages are doing the job it was meant to do, and we can just delete it?

It seems to me like each of these major hosting features should probably be it's own feature page (CDN, Custom 404, Sitemaps, robots.txt), and we should remove the marketing copy at the top.

I can do that refactor tomorrow if you agree that is a reasonable path forward.

benjaoming · 2023-02-08T14:55:57Z

Sorry, was taking a long time to digest this!!

I agree. The "hosting" umbrella wasn't very good, and each of these features go beyond what hosting means.

The reference/features/ structure can hold many feature descriptions and I think that adding these pages individually there would be a welcome "content dumping" for the next step of putting together a good feature reference overview.

ericholscher · 2023-02-08T23:39:13Z

Great! I will try to knock that out this week. 👍

Ended up writing a bunch of additional content here, since these features were barely documented... This will be a big win for our users.

ericholscher · 2023-02-10T01:16:40Z

Just pushed an initial refactor of features into dedicated pages.

Ended up writing a bunch of additional content here,
since these features were barely documented...

This will be a big win for our users.

benjaoming · 2023-02-10T10:41:01Z

@ericholscher I've added a bunch of suggestions but I'll hold off a bit.

If you recall #9983, there are some changes in diataxis/main waiting.

I think it's best if you merge and resolve conflicts firstly and then I'll continue reviewing 👍

benjaoming

This is looking great 👍

I stopped the review midway... My goal was to add EVERYTHING as a suggestion :) I succeeded so far.. but am a bit worried about the merge conflicts that are coming up.

benjaoming · 2023-02-10T10:09:04Z

docs/Makefile

@@ -7,7 +7,7 @@
 # (except for '--keep-going', failing fast is prefered on local builds)
 # We also remove '-E' to reduce the time of rebuilding reference indexes
 # on each build.
-SPHINXOPTS    = -T -j auto -W
+SPHINXOPTS    = -T -W


Pretty sure that -j auto is the default in our Sphinx builder?

Oh yea, I was getting errors on this locally, but I just needed to update my depednencies.

docs/user/reference/cdn.rst

docs/user/reference/features.rst

ericholscher · 2023-02-10T15:06:14Z

I stopped the review midway... My goal was to add EVERYTHING as a suggestion :) I succeeded so far.. but am a bit worried about the merge conflicts that are coming up.

Yea, I saw those. Shouldn't be too bad to resolve, since I'm mostly just adding new pages. I assume it'll be just using the existing TOCTree, add the 4 files, and the content up top.

benjaoming · 2023-02-10T15:50:13Z

Resolving conflicts...

…g into diataxis/split-hosting-features

…nx DirHTML builder.

benjaoming · 2023-02-10T16:02:53Z

Rrrrrrrrrrrrrreeeeeee--solved!

benjaoming · 2023-02-10T16:27:00Z

Continuing the review...

benjaoming

Alright, here comes another round of suggestions!

I hope I didn't mess up and write comments that weren't directly phrased as suggestions :)

docs/user/reference/404-not-found.rst

benjaoming · 2023-02-10T16:33:09Z

docs/user/reference/features.rst

+  integrated nicely into the URL of your documentation.
+  This is served at ``/en/latest/`` by default.
+  If you only have 1 version and translation,
+  we also support :doc:`single version projects </single_version>` served at ``/``.


This is a really nice purposeful use of the introduction, clarifying a basic misconception that somehow multiple versions are required 👍

docs/user/reference/robots.rst

docs/user/reference/sitemaps.rst

Co-authored-by: Benjamin Balder Bach <[email protected]>

ericholscher · 2023-02-13T20:42:26Z

@benjaoming Should be ready for a final 👍 if it looks good.

benjaoming

Now builds and looks good!! Thanks, this was a big one!

Updated reference for hosting features, adding more features and re-o…

b14e129

…rganizing content

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

benjaoming requested a review from a team as a code owner January 26, 2023 16:05

benjaoming requested a review from agjohnson January 26, 2023 16:05

auto-assign bot assigned benjaoming Jan 26, 2023

benjaoming changed the title ~~Docs: Reorganize hosting features as reference (Diátaxis)~~ Docs: Relabel and reorganize hosting features as reference (Diátaxis) Jan 26, 2023

benjaoming mentioned this pull request Jan 26, 2023

Docs: Diátaxis refactor - iteration 1 high-level tracking #9746

Closed

38 tasks

agjohnson requested review from ericholscher and removed request for agjohnson January 30, 2023 17:52

ericholscher reviewed Jan 30, 2023

View reviewed changes

benjaoming and others added 9 commits February 1, 2023 11:31

Merge branch 'diataxis/main' of github.com:readthedocs/readthedocs.or…

1e0e846

…g into diataxis/split-hosting-features

Apply suggestions from code review @ericholscher

3c5a569

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

Update name of Feature reference index to avoid explicit labels elsew…

78ac176

…here

Fix misalignments

e11f180

Redo in-page references

9c38f27

Update "read more" link for "multiple documentation versions"

a5323b6

Add "private documentation" to hosting feature list

c3ac6de

Revert to old title, modify introduction with less passive voice

e885bc7

Dot the list sentences, don't say "bust" but "invalidate and refresh"

0a36b8b

ericholscher self-requested a review February 1, 2023 23:54

Refactor of feature section

4d8dd32

benjaoming assigned ericholscher Feb 8, 2023

Initial refactor of features into dedicated pages.

2022d5b

Ended up writing a bunch of additional content here, since these features were barely documented... This will be a big win for our users.

ericholscher added 2 commits February 9, 2023 17:22

More refactoring

6f71b64

Remove redundancy

c7e5fb2

benjaoming commented Feb 10, 2023

View reviewed changes

Remove stray Makefile commit

3294054

benjaoming added 2 commits February 10, 2023 16:56

Merge branch 'diataxis/main' of github.com:readthedocs/readthedocs.or…

118aae6

…g into diataxis/split-hosting-features

Make a mention of this "404/index.html" structure in relation to Sphi…

2b192a5

…nx DirHTML builder.

benjaoming commented Feb 10, 2023

View reviewed changes

Apply suggestions from code review

afa0ec8

Co-authored-by: Benjamin Balder Bach <[email protected]>

benjaoming added 2 commits February 14, 2023 15:22

Lint

419dccf

Fix typo

2435b30

benjaoming commented Feb 14, 2023

View reviewed changes

benjaoming merged commit 739fd3b into readthedocs:diataxis/main Feb 14, 2023

benjaoming deleted the diataxis/split-hosting-features branch February 14, 2023 15:12

ericholscher mentioned this pull request Feb 14, 2023

Docs: Refactor the build & build customization pages (Diátaxis) #10028

Merged

Uh oh!

Docs: Relabel and reorganize hosting features as reference (Diátaxis) #9952

Docs: Relabel and reorganize hosting features as reference (Diátaxis) #9952

Uh oh!

Conversation

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

Uh oh!

Uh oh!

ericholscher commented Jan 30, 2023

Uh oh!

ericholscher left a comment • 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benjaoming commented Feb 1, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ericholscher commented Feb 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

benjaoming commented Feb 8, 2023

Uh oh!

ericholscher commented Feb 8, 2023

Uh oh!

ericholscher commented Feb 10, 2023

Uh oh!

benjaoming commented Feb 10, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

benjaoming left a comment

Choose a reason for hiding this comment

Uh oh!

benjaoming Feb 10, 2023

Choose a reason for hiding this comment

Uh oh!

ericholscher Feb 10, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ericholscher commented Feb 10, 2023

Uh oh!

benjaoming commented Feb 10, 2023

Uh oh!

benjaoming commented Feb 10, 2023

Uh oh!

benjaoming commented Feb 10, 2023

Uh oh!

benjaoming left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

benjaoming Feb 10, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ericholscher commented Feb 13, 2023

benjaoming commented Jan 26, 2023 •

edited by github-actions bot

Loading

ericholscher left a comment •

edited

Loading

benjaoming commented Feb 1, 2023 •

edited

Loading

ericholscher commented Feb 2, 2023 •

edited

Loading

benjaoming commented Feb 10, 2023 •

edited

Loading