In the last year, we have been focusing ourselves on providing a better experience for authors and readers of the documentation.
Today, we are thrilled to introduce our latest feature,
designed around user feedback to build a better user experience: Read the Docs Addons.
Read the Docs Addons helps authors to keep their documentation updated by focusing on the most relevant pages,
while simplifying the review process --and also helps readers to navigate the documentation in a simple way,
always knowing the versions they are reading avoiding confusions.
Continue reading to explore the full list of addons and how to enable them in your project.
How to enable addons in your project
To enable Read the Docs Addons in your project follow these steps:
- Go to the new beta dashboard:
- Community
- Business
- Click on the project you want to enable addons.
- Go to Settings, then Addons (Beta) from the left bar.
- Check Enable Addons.
Now you have Read the Docs Addons enabled,
readers of your documentation can start using these features.
Full list of addons
Analytics
Analytics allows authors to explore your documentation traffic to understand what are the pages readers read the most.
With this data, your team is able to prioritize the work on pages with high traffic over others with less.
Besides, you can find out what are the terms your users search the most and
write documentation pages that include those terms so they can easily find them.
DocDiff
DocDiff shows changes made on the rendered versions by visually highlighting the differences between
the current pull request and the latest version of the project's documentation.
This addons allows reviewers to quickly find what has changed on this pull request
but also find style/rendering issues before accepting and merging the pull request.
To show the differences on a pull request against the latest version,
the reader can press d on their keyboard to enable/disable.
Pull request notification
This notification warns users letting them know the documentation page they are reading
comes from a pull request to clearly distinguish this version from the official one.
Flyout
The flyout is the small floating Read the Docs section where all the documentation versions and translations are listed.
This allows readers to find the exact version they are looking for and also read the documention in their own language if it's available.
Besides, it contains useful links to go to the project's home, builds page and offline formats such as PDFs and ebooks.
Non-stable notification
A notification on all non-stable versions is shown to clearly communicate to readers
they may be reading an outdated version of the documentation.
This helps readers to avoid confusion and quickly jump into the stable version of the documentation.
Besides, it reduces support requests from old version of your product.
Latest version notification
A notification shown on the latest version tells readers
they are reading the latest/development version of the documentation that may include features not yet deployed.
This will help your readers to avoid confusion on the version they are using and the one they are reading,
while letting your project to expose these yet unreleased features.
Search as you type
Search as-you-type is powered by an Elasticsearch backend that allows users to quickly find exactly what they are looking for while typing.
It also saves recent searches to have them at the tip of your fingers.
Sponsorship
EthicalAds is the business model that allows Read the Docs to continue being a free web service.
It respects users while providing value to advertisers.
We don’t track you, sell your data, or anything else.
We simply show ads to users, based on the content of the page you're currently looking at.
Moving forward
We have implemented Read the Docs Addons in a modular way that allows us to expand them in the future.
There are plans to keep adding more addons to this list and also re-implement some of the Sphinx extension we've created in the past
(e.g. sphinx-hoverxref) as an addon,
making it compatible with non-Sphinx projects.
We are also open to suggestions for new addons, let us know if you have an idea!
Conclusion
Read the Docs provides a lot of features for documentation authors to simplify their workflow and to keep the documentation updated,
providing pull request previews, automation rules, versioning, translation, and many other features.
The introduction of Read the Docs Addons, empowers the readers' experience as well, closing the circle between authors and readers.
Addons give readers a quick way to find what they are looking for,
notifies them about reading the latest version which may have features that are not yet implemented or,
an old version that may be deprecated.
It gives them a way to quickly switch between versions and translations of the same page,
and much more in near future!
Contact us if you have any questions about the new beta Read the Docs Addons,
or open an issue to share any feedback you may have.
