Docs: Refactor and simplify our docs #7052
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Also upgrade Sphinx to 3+
Alternatively, we can make a one-off requirements file for just the docs if we can't upgrade to Sphinx 3.0.3 yet.
Most of the information about search was in a guide, I think we should document this as a feature.
I’ve mostly focused on the first two sections of the docs, and tried to make them a lot simpler and less technical. The goal here is for more users to be able to understand product features instead of implementation at the developer level. I’ve also added a bit more sales and branding content that I think is important for folks to understand what exactly RTD is. I think this helps us communicate and sell the message of what we’re building, and hoepfully get aligned users on our side.
ericholscher
requested review from
dojutsu-user and
a team
and removed request for
dojutsu-user
agjohnson
reviewed
May 8, 2020
Co-authored-by: Anthony <[email protected]>
Co-authored-by: Anthony <[email protected]>
Co-authored-by: Anthony <[email protected]>
|
Would be good to document that we serve a default 404, sitemap and robots pages (and some of them can be overridden). I think they are hidden in the guides now. |
davidfischer
approved these changes
May 8, 2020
| Think of it as *Continuous Documentation*. | ||
|
|
||
| Never out of sync | ||
| Never out of sync |:arrows_counterclockwise:| |
There was a problem hiding this comment.
Emojis are really good here.
BTW, I don't like how this renders in the new version of the theme, but I suppose that's a bug.
davidfischer
reviewed
May 8, 2020
- Add more links to the config file and specifying dependencies - Add link to remove advertising - Change order based on perceived need - De-emphasize feature flags
I added the Hosting Features page to address this 👍 |
stsewd
reviewed
May 9, 2020
docs/faq.rst
Outdated
| .. _html_extra_path: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_extra_path | ||
| .. _docs_dir: https://www.mkdocs.org/user-guide/configuration/#docs_dir | ||
| We also keep an up-to-date :doc:`changelog </changelog>`. | ||
| >>>>>>> origin/davidfischer/minor-faq-rework |
stsewd
reviewed
May 9, 2020
tox.ini
Outdated
| @@ -51,7 +51,7 @@ description = run linter (rstcheck) to ensure there aren't errors on our docs | |||
| deps = -r{toxinidir}/requirements/docs-lint.txt | |||
| changedir = {toxinidir}/docs | |||
| commands = | |||
| rstcheck -r . | |||
| rstcheck -r --ignore-substitutions org_brand,com_brand . | |||
There was a problem hiding this comment.
humitos
approved these changes
May 11, 2020
| If your business is hitting build limits hosting documentation on Read the Docs, | ||
| please consider :doc:`Read the Docs for Business </commercial/index>` | ||
| which has much higher build resources. | ||
| .. tab:: |org_brand| |
| Think of it as *Continuous Documentation*. | ||
|
|
||
| Never out of sync | ||
| Never out of sync |:arrows_counterclockwise:| |
There was a problem hiding this comment.
Emojis are really good here.
BTW, I don't like how this renders in the new version of the theme, but I suppose that's a bug.
Co-authored-by: Manuel Kaufmann <[email protected]>
Closed
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I’ve mostly focused on the first two sections of the docs, and tried to
make them a lot simpler and less technical. The goal here is for more users
to be able to understand product features instead of implementation at the
developer level.
I’ve also added a bit more sales and branding content that I think is
important for folks to understand what exactly RTD is. I think this helps
us communicate and sell the message of what we’re building, and hopefully
get aligned users on our side.
Refs #7055 -- I pulled those changes in too
Review
The best way to review this is going to be looking at the rendered docs, I think: https://docs--7052.org.readthedocs.build/en/7052/
It's a lot of content changes, and it's pretty difficult to review in the diff viewer.
The most interesting pages: