Skip to content

Docs: Navigation menu wrap-up: About, Features and Advanced Features as Reference (Diátaxis) #10010

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.

Sign up for GitHub

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

Merged
merged 9 commits into from
Feb 14, 2023
Merged

Docs: Navigation menu wrap-up: About, Features and Advanced Features as Reference (Diátaxis) #10010

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
43cf5f8
Collects About Read the Docs and Features and Advanced Features in Re…
benjaoming Feb 9, 2023
f23f223
Merge branch 'diataxis/main' of github.com:readthedocs/readthedocs.or…
benjaoming Feb 10, 2023
8c9476a
Reorder a few things
benjaoming Feb 10, 2023
331a3f2
Add 🔗 for Developer Documentation
benjaoming Feb 10, 2023
f7777bc
Having a go at explaining the website and how we use documentation to…
benjaoming Feb 10, 2023
fe18295
Merge branch 'diataxis/main' of github.com:readthedocs/readthedocs.or…
benjaoming Feb 14, 2023
90ddc5d
Apply suggestions from @ericholscher's code review
benjaoming Feb 14, 2023
d5ab3d7
Move seealso to after the list
benjaoming Feb 14, 2023
ea382c7
remove non-existing TOC ref
benjaoming Feb 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 48 additions & 1 deletion docs/user/about.rst → docs/user/about/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,22 @@
About Read the Docs
===================

.. toctree::
:hidden:

/commercial/index
/reference/policies
/advertising/index
/story
/sponsors
/open-source-philosophy
/team
/support

Read the Docs is a C Corporation registered in Oregon.
Our bootstrapped company is owned and fully controlled by the founders,
and fully funded by our customers and advertisers.
This allows us to **focus 100% on our users**.
This allows us to **focus 100% on our users**.

We have two main sources of revenue:

Expand All @@ -25,3 +37,38 @@ This allows us to give back to the communities and projects that we support and

We are proud about the way we manage our company and products,
and are glad to have you on board with us in this :doc:`great documentation journey </story>`.

Additional content
-------------------------------

If you want to dive more into more specific information and our policies,
we've brought most of the most important ones below.

⏩ :doc:`/commercial/index`
Learn more about how our company provides paid solutions

⏩ :doc:`/reference/policies`
Policies and legal documents used by |org_brand| and |com_brand|.

⏩ :doc:`/advertising/index`
Information about how advertisement in Read the Docs

⏩ :doc:`/story`
A brief throwback to how we were founded

⏩ :doc:`/sponsors`
Read about who currently sponsors Read the Docs and who sponsored us in the past.

⏩ :doc:`/open-source-philosophy`
Our philosophy is anchored in open source.

⏩ :doc:`/team`
How we work and who we are.

⏩ :doc:`/support`
Read this before asking for help: How to get support and where.

.. seealso::

`Our website <https://about.readthedocs.com>`__
Our primary website has general-purpose information about Read the Docs like pricing and feature overviews.
2 changes: 1 addition & 1 deletion docs/user/features.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,4 +88,4 @@ Our bootstrapped company is owned and controlled by the founders,
and fully funded by our customers and advertisers.
That allows us to focus 100% of our attention on building the best possible product for you.

Learn more :doc:`/about`.
Learn more :doc:`/about/index`.
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Created a directory here.

It's not immediately in use. But the intention was to have an actual collection of articles, spanning some existing items once that we start doing path refactors and redirects (which we have said not to do right now)

Because of DirHTML, this shouldn't make a difference right now.

55 changes: 7 additions & 48 deletions docs/user/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Multiple versions |:card_index_dividers:|

Open Source and User Focused |:heartbeat:|
Our code is free and `open source <https://github.com/readthedocs/>`_.
:doc:`Our company </about>` is bootstrapped and 100% user focused.
:doc:`Our company </about/index>` is bootstrapped and 100% user focused.
|org_brand| hosts documentation for over 100,000 large
and small open source projects,
in almost every human and computer language.
Expand Down Expand Up @@ -109,12 +109,15 @@ to help you create fantastic documentation for your project.
:caption: Reference
:glob:

/reference/features
Copy link
Member

@ericholscher ericholscher Feb 10, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

💯

I think this page is what should replace https://docs.readthedocs.io/en/stable/hosting.html -- a really nice feature index with highlights of each feature.

Similar to our landing pages, a feature highlight, that drops into that feature detail... 🤔
Screenshot 2023-02-09 at 4 27 09 PM

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes, when we introduced it, we said to start using it as the new index -- but we just postponed the design of the index for next iteration :)

I think the work to move the hosting features in as a description list is great, we can probably do that for other pages, too. But it's best to do in just one PR, otherwise we get Git conflicts galore :)

/api/index
/server-side-search/api
/reference/features
/server-side-search/syntax
/reference/policies
/reference/environment-variables
changelog
Developer Documentation 🔗 <https://dev.readthedocs.io>
/about/index
/glossary


Read the Docs feature overview
Expand Down Expand Up @@ -150,20 +153,6 @@ and some of the core features of Read the Docs.
:doc:`/support` |
:doc:`/faq`

.. toctree::
:maxdepth: 1
:hidden:
:caption: Features
Copy link
Member

Choose a reason for hiding this comment

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

🔥


/config-file/index
/integrations
/versions

/builds
/build-customization

/support


How-to Guides
-------------
Expand Down Expand Up @@ -228,16 +217,6 @@ out of your documentation and Read the Docs.
* **Extending Read the Docs**:
:doc:`REST API <api/index>`

.. toctree::
:maxdepth: 2
:hidden:
:glob:
:caption: Advanced features

flyout-menu
feature-flags
canonical-urls



Read the Docs for Business
Expand Down Expand Up @@ -268,7 +247,7 @@ of Read the Docs and the larger software documentation ecosystem.


* **The people and philosophy behind Read the Docs**:
:doc:`About Us </about>` |
:doc:`About Us </about/index>` |
:doc:`Team <team>` |
:doc:`Open source philosophy <open-source-philosophy>` |
:doc:`Our story <story>`
Expand All @@ -285,23 +264,3 @@ of Read the Docs and the larger software documentation ecosystem.
* **Getting involved with Read the Docs**:
:doc:`/glossary` |
:doc:`Developer Documentation <rtd-dev:index>`


.. toctree::
:maxdepth: 1
:hidden:
:caption: About Read the Docs

changelog

about
/commercial/index
team
open-source-philosophy
story

advertising/index
sponsors

Developer Documentation <https://dev.readthedocs.io>
glossary
12 changes: 11 additions & 1 deletion docs/user/reference/features.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,6 @@ Hosting features

../features
analytics
/feature-flags
/server-side-search/index
/automation-rules
/user-defined-redirects
Expand All @@ -74,6 +73,17 @@ Hosting features
/reference/robots
/reference/sitemaps
/security-log

/config-file/index
/integrations
/versions

/builds
/build-customization
/environment-variables
/flyout-menu
/canonical-urls
/feature-flags
/commercial/organizations
/commercial/privacy-level
/commercial/sharing
Expand Down