Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Refactor and simplify our docs #7052

Merged
merged 29 commits into from May 12, 2020
Merged

Docs: Refactor and simplify our docs #7052

merged 29 commits into from May 12, 2020

Conversation

ericholscher
Copy link
Member

@ericholscher ericholscher commented May 8, 2020

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:

agjohnson and others added 5 commits May 6, 2020
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 ericholscher requested review from dojutsu-user and and removed request for dojutsu-user May 8, 2020
Copy link
Contributor

@agjohnson agjohnson left a comment

Looks great! I'm happy to see the technical focus reduced in these docs.

docs/features.rst Outdated Show resolved Hide resolved
docs/features.rst Outdated Show resolved Hide resolved
docs/features.rst Outdated Show resolved Hide resolved
docs/features.rst Outdated Show resolved Hide resolved
docs/guides/searching-with-readthedocs.rst Outdated Show resolved Hide resolved
docs/about.rst Outdated Show resolved Hide resolved
docs/about.rst Outdated Show resolved Hide resolved
docs/automatic-redirects.rst Outdated Show resolved Hide resolved
docs/builds.rst Outdated Show resolved Hide resolved
docs/builds.rst Show resolved Hide resolved
@ericholscher ericholscher requested review from and davidfischer May 8, 2020
ericholscher and others added 4 commits May 8, 2020
Co-authored-by: Anthony <aj@ohess.org>
Co-authored-by: Anthony <aj@ohess.org>
Co-authored-by: Anthony <aj@ohess.org>
@stsewd
Copy link
Member

stsewd commented May 8, 2020

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.

docs/downloadable-formats.rst Outdated Show resolved Hide resolved
docs/features.rst Outdated Show resolved Hide resolved
docs/intro/getting-started-with-mkdocs.rst Show resolved Hide resolved
Think of it as *Continuous Documentation*.

Never out of sync
Never out of sync |:arrows_counterclockwise:|
Copy link
Contributor

@davidfischer davidfischer May 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❤️

Copy link
Member

@humitos humitos May 11, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

docs/conf.py Show resolved Hide resolved
ericholscher and others added 5 commits 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
@ericholscher
Copy link
Member Author

ericholscher commented May 8, 2020

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.

I added the Hosting Features page to address this 👍

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
Copy link
Member

@stsewd stsewd May 9, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This shouldn't be here 👀

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 .
Copy link
Member

@stsewd stsewd May 9, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Member

@humitos humitos left a comment

I like the refactor. I made some comments/suggestions to consider.

docs/automatic-redirects.rst Outdated Show resolved Hide resolved
docs/builds.rst Outdated Show resolved Hide resolved
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|
Copy link
Member

@humitos humitos May 11, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💯

docs/config-file/v2.rst Outdated Show resolved Hide resolved
docs/development/buildenvironments.rst Outdated Show resolved Hide resolved
docs/faq.rst Show resolved Hide resolved
docs/faq.rst Outdated Show resolved Hide resolved
docs/features.rst Outdated Show resolved Hide resolved
Think of it as *Continuous Documentation*.

Never out of sync
Never out of sync |:arrows_counterclockwise:|
Copy link
Member

@humitos humitos May 11, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

docs/server-side-search.rst Outdated Show resolved Hide resolved
ericholscher and others added 2 commits May 11, 2020
Co-authored-by: Manuel Kaufmann <humitos@gmail.com>
@ericholscher ericholscher mentioned this pull request May 11, 2020
@ericholscher ericholscher merged commit a24b731 into master May 12, 2020
1 of 2 checks passed
@ericholscher ericholscher deleted the docs-refactor branch May 12, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants