Fix content issues with high priority doc pages

[agjohnson]

@humitos noted in chat:

The first step is to decide those top 5 features, which I think they are:

• versioning

• full-text search

• pull request preview

• build customization

• custom domains with instant SSL support

• for Business, add to that list as well:

  • CDN
  • SSO
  • auth auditing

That said, I think these are the pages we should focus on initially:

Note that these pages should be listed at the top of the "Feature overview" title in the left sidebar instead of hidden between other less relevant features.

• Docs: update features page
  • improve that page mentioning those top 5 features that immediately catches readers' attention (using more marketing language)
  • currently, pull request preview is not even mentioned there 😞
• Docs: update versions/versioning page #9572
  • in-depth but simple explanation about how it works
  • explain how latest and stable work with more narrative content
  • remove deprecated VCS (svn, bzr) from the table --maybe remove the table completely after that since there is no differentiation to do
• Docs: update search page #9573
  • we call the feature "full-text search" support, but the page is named "Server Side Search"; we should probably unify them
  • the content looks good to me, just some minor edits would be fine for now
• Docs: update pull request page #9574
  • the content looks good, it could use a more marketing language to sell it more, but it's fine for now
  • maybe some small edits will help
• Docs: update builds and build customization page #9575
  • these page were updated some weeks ago
  • anthony made some notes of improvements he wanted to see here, so we can recover those notes and update it
• Docs: add page on team management and authentication #9576
  • This is a page that is missing currently
  • How to use teams to isolate projects, etc
  • How to invite into teams
• Docs: update user redirects
• Docs: update custom domains page
  • starts talking about subdomain support, why? the page is about custom domains. That seems distracting to me and could be moved to another page where we talk about hosting features or similar
  • the main section "Custom domain support" could have more narrative content
  • the content from this section could be moved to "Configuration" to keep consistency with other feature pages
  • mention SSL support bigger :)
  • canonical URLs content can be improved a little
• Docs: update downloadable documentation page #9577
  • "Offline formats" is the nomenclature used in new application templates and
    the website
  • (https://docs.readthedocs.io/en/latest/downloadable-documentation.html)

[agjohnson]

That features page definitely does need a makeover, but it is going to overlap with the features page on our website, which we do need a page like that with more marketing focus.

I would be fine authoring the content for features on our website, and maybe linking the docs to our website in some way? This interaction isn't super clear to me right now though, and I feel we'll be dealing with this more often, as we author more website content.

Do we have opinions about patterns here? Specifically, where what is the delineation between website content and documentation content?

I might propose that the website features page is marketing focused and the documentation page features content is very detail oriented, but not as marketing focused. I think this is also the content that I commonly want for users -- guides on using our features/etc.

[humitos]

I think I'm aligned with what you are describing here. I'd prefer to have the documentation details in our documentation and the marketing page on our website. Marketing pages on the website can describe the benefits of using the feature with some narrative content explaining different use cases. On the other hand, the documentation should have all the deep details about the feature (e.g. commands you have to run, how to validate it's working as you expected, troubleshooting sections, how to enable it via the UI, or the YAML required in the config file).

[ericholscher]

I agree with that, but do think we want to cover the benefits of the feature in the docs as well. We need to do a little selling of the feature, which is also good documentation so people can understand why they'd want to enable it.

[benjaoming]

The current state with two different "Feature Overview" is quite bad, as it makes the state of the user docs look disorganized or accidental.

[agjohnson]

Would these be better off as individual items? We've been punting this one from sprint to sprint for a while now, so doesn't seem like something we're actively working on.

[agjohnson]

I pushed all these sub issues out to individual issues. We can shape up the work there and continue with assignment etc later. I pushed all of them on our Q4 roadmap, as we haven't been good about addressing these issues so far. I've been talking about making our Q4 focus lean towards debt and UX cleanup, as an extension to improving our user experience in Q3.

I'll close this so we can stop shuffling it on our sprints, feel free to take any of the sub tasks however!