diff --git a/content/images/addons-analytics.png b/content/images/addons-analytics.png new file mode 100644 index 0000000..6c4809c Binary files /dev/null and b/content/images/addons-analytics.png differ diff --git a/content/images/addons-docdiff.gif b/content/images/addons-docdiff.gif new file mode 100644 index 0000000..0ed4be8 Binary files /dev/null and b/content/images/addons-docdiff.gif differ diff --git a/content/images/addons-ethical-ads.png b/content/images/addons-ethical-ads.png new file mode 100644 index 0000000..ca858c9 Binary files /dev/null and b/content/images/addons-ethical-ads.png differ diff --git a/content/images/addons-flyout.png b/content/images/addons-flyout.png new file mode 100644 index 0000000..67da11a Binary files /dev/null and b/content/images/addons-flyout.png differ diff --git a/content/images/addons-latest-notification.png b/content/images/addons-latest-notification.png new file mode 100644 index 0000000..6f9b4ce Binary files /dev/null and b/content/images/addons-latest-notification.png differ diff --git a/content/images/addons-non-stable-notification.png b/content/images/addons-non-stable-notification.png new file mode 100644 index 0000000..a0f0801 Binary files /dev/null and b/content/images/addons-non-stable-notification.png differ diff --git a/content/images/addons-pull-request-notification.png b/content/images/addons-pull-request-notification.png new file mode 100644 index 0000000..53e107a Binary files /dev/null and b/content/images/addons-pull-request-notification.png differ diff --git a/content/images/addons-search.gif b/content/images/addons-search.gif new file mode 100644 index 0000000..0eda21f Binary files /dev/null and b/content/images/addons-search.gif differ diff --git a/content/images/enable-beta-addons.jpg b/content/images/enable-beta-addons.jpg new file mode 100644 index 0000000..429b40c Binary files /dev/null and b/content/images/enable-beta-addons.jpg differ diff --git a/content/posts/enable-beta-addons.md b/content/posts/enable-beta-addons.md new file mode 100644 index 0000000..b2e8eae --- /dev/null +++ b/content/posts/enable-beta-addons.md @@ -0,0 +1,138 @@ +title: Empower your documentation with addons +date: 2024-04-25 +description: Read the Docs Addons let documentation authors add features to their documentation such as analytics, version feedback, and search as you type to documentation in a modular way where authors have control. +category: Feature announcement +tags: addons, hosting +authors: Manuel Kaufmann +status: published +image: /images/enable-beta-addons.jpg +image_credit: Photo by <a href="https://unsplash.com/@impatrickt?utm_content=creditCopyText&utm_medium=referral&utm_source=unsplash">Patrick Tomasso</a> on <a href="https://unsplash.com/photos/open-book-lot-Oaqk7qqNh_c?utm_content=creditCopyText&utm_medium=referral&utm_source=unsplash">Unsplash</a> + + +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: + +1. Go to the new beta dashboard: + * [Community](https://beta.readthedocs.org) + * [Business](https://beta.readthedocs.com) +1. Click on the project you want to enable addons. +1. Go to **Settings**, then **Addons (Beta)** from the left bar. +1. 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 Addons](/images/addons-analytics.png) + +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 Addons](/images/addons-docdiff.gif) + +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 + +![Pull request notification](/images/addons-pull-request-notification.png) + +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 + +![Flyout Addons](/images/addons-flyout.png) + +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 + +![Non-stable notification](/images/addons-non-stable-notification.png) + +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 + +![Latest notification](/images/addons-latest-notification.png) + +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](/images/addons-search.gif) + +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](/images/addons-ethical-ads.png) + +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`](https://github.com/readthedocs/sphinx-hoverxref)) as an addon, +making it compatible with non-Sphinx projects. + +We are also open to suggestions for new addons, [let us](https://github.com/readthedocs/addons/issues) 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 + +[Contact us](https://readthedocs.org/support/) if you have any questions about the new beta Read the Docs Addons, +or [open an issue](https://github.com/readthedocs/addons) to share any feedback you may have.