From f784be29ca7598b76d673f3bfbc4fe5ec04fccdd Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Wed, 22 Feb 2023 15:21:32 -0800 Subject: [PATCH 01/34] Write a very bad introduction to structuring docs I got motivated to write this, but struggled to figure out what to say in a clear way.. Leaving this in a draft for another day. --- .../explanation/documentation-structure.rst | 43 +++++++++++++++++++ docs/user/index.rst | 1 + 2 files changed, 44 insertions(+) create mode 100644 docs/user/explanation/documentation-structure.rst diff --git a/docs/user/explanation/documentation-structure.rst b/docs/user/explanation/documentation-structure.rst new file mode 100644 index 00000000000..9393592124e --- /dev/null +++ b/docs/user/explanation/documentation-structure.rst @@ -0,0 +1,43 @@ +How to structure your documentation +=================================== + +Structuring your documentation is an important part of the authoring process. +It's important to think about the reader of the documentation, +since they are the primary user of documentation. + +One of the largest benefits of a good structure is that it removes questions that keep authors from writing documentation. +Starting with a blank page is often the hardest part of documentation, +so anything we can do to remove this problem is a win. + +Recommendations for process +--------------------------- + +In order to avoid starting with a blank page, +we recommend a simple process: + +* Choose a structure for your documentation. We recommend `Diátaxis `_ for this. +* Find a :doc:`example project ` or template to start from. +* Start writing by filling in the structure. + +This process helps you get started quickly, +and helps keep things consistent for the reader of your documentation. + +Diátaxis +-------- + +The documentation you're reading is written using the Diátaxis framework. +It has four major parts as summarized by this image: + +.. image:: https://diataxis.fr/_images/diataxis.png + +We recommend that you read more about Diátaxis in the `documentation `_ for it. + +Explaining the structure to your users +------------------------------------- + +One of the benefits of Diátaxis is that it's a well-known structure, +and users might already be familiar with it. +As long as you stick to the structure, +your users should be able to use existing experience to navigate. + +Using the names that are defined (eg. Tutorials, Explanation) in a user-facing way also helps here. diff --git a/docs/user/index.rst b/docs/user/index.rst index 833d53b2b54..0cf87dcc091 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -18,6 +18,7 @@ Read the Docs: Documentation Simplified :caption: 💡 Explanation /choosing-a-site + /explanation/documentation-structure /integrations /downloadable-documentation /environment-variables From 74300b68e7ee5e1651d0668b808a05125f05e7e9 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 24 Feb 2023 19:09:32 +0100 Subject: [PATCH 02/34] Refactor Explanation navigation for new sub-levels --- docs/user/index.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/user/index.rst b/docs/user/index.rst index 4413dd4503d..fd92ba5773f 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -19,10 +19,8 @@ Read the Docs: documentation simplified /choosing-a-site /integrations - /downloadable-documentation - /environment-variables - /subprojects - /localization + /explanation/methodology + /explanation/advanced .. toctree:: :maxdepth: 2 From 2016b79dbca700dc3ebd2f9ad92403072f773868 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 24 Feb 2023 20:13:08 +0100 Subject: [PATCH 03/34] Add new topics --- docs/user/explanation/advanced.rst | 12 ++++++++++ ...cumentation-structure.rst => diataxis.rst} | 2 +- docs/user/explanation/methodology.rst | 23 +++++++++++++++++++ docs/user/index.rst | 1 - 4 files changed, 36 insertions(+), 2 deletions(-) create mode 100644 docs/user/explanation/advanced.rst rename docs/user/explanation/{documentation-structure.rst => diataxis.rst} (97%) create mode 100644 docs/user/explanation/methodology.rst diff --git a/docs/user/explanation/advanced.rst b/docs/user/explanation/advanced.rst new file mode 100644 index 00000000000..d009b2e47c9 --- /dev/null +++ b/docs/user/explanation/advanced.rst @@ -0,0 +1,12 @@ +Deep dive into Read the Docs +============================ + + +.. toctree:: + :maxdepth: 2 + :hidden: + + /downloadable-documentation + /environment-variables + /subprojects + /localization diff --git a/docs/user/explanation/documentation-structure.rst b/docs/user/explanation/diataxis.rst similarity index 97% rename from docs/user/explanation/documentation-structure.rst rename to docs/user/explanation/diataxis.rst index 9393592124e..4621a966297 100644 --- a/docs/user/explanation/documentation-structure.rst +++ b/docs/user/explanation/diataxis.rst @@ -33,7 +33,7 @@ It has four major parts as summarized by this image: We recommend that you read more about Diátaxis in the `documentation `_ for it. Explaining the structure to your users -------------------------------------- +-------------------------------------- One of the benefits of Diátaxis is that it's a well-known structure, and users might already be familiar with it. diff --git a/docs/user/explanation/methodology.rst b/docs/user/explanation/methodology.rst new file mode 100644 index 00000000000..98fb55a8628 --- /dev/null +++ b/docs/user/explanation/methodology.rst @@ -0,0 +1,23 @@ +Methodology and best practice +============================= + +In this section, +we are covering important methods and best practices that will make your documentation better. + +You can familiarize yourself with these topics before or after writing documentation. +We encourage that you read this at any time, +as each section gives approaches +regardless of whether you need to create new content or restructure larger documentation sets. + +:doc:`The Diátaxis Methodology ` + In order to understand documentation in the most general and fundamental sense, + we introduce the Diátaxis methodology which is also used for the documentation you are now reading. + +Best practice: Search Engine Optimization + It's important that your documentation can be found using search engines. + +.. toctree:: + :maxdepth: 2 + :hidden: + + diataxis diff --git a/docs/user/index.rst b/docs/user/index.rst index fe8e439939d..fd92ba5773f 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -18,7 +18,6 @@ Read the Docs: documentation simplified :caption: 💡 Explanation /choosing-a-site - /explanation/documentation-structure /integrations /explanation/methodology /explanation/advanced From 4119923f7d95d2f74ce678f900ba4505c720bca7 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 24 Feb 2023 20:14:07 +0100 Subject: [PATCH 04/34] Add suggestions from previous PR --- docs/user/explanation/diataxis.rst | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/docs/user/explanation/diataxis.rst b/docs/user/explanation/diataxis.rst index 4621a966297..c984f68dbd8 100644 --- a/docs/user/explanation/diataxis.rst +++ b/docs/user/explanation/diataxis.rst @@ -1,16 +1,29 @@ How to structure your documentation =================================== -Structuring your documentation is an important part of the authoring process. -It's important to think about the reader of the documentation, -since they are the primary user of documentation. +A documentation project's ultimate goal is to be read and understood by a reader. +Readers need to be able to :term:`discover ` the information that they need. +Without an intuitive structure, +readers either won't find information that they need or get frustrated on the way. +Having a structure in mind can happen from the very beginning of a documentation project. +Changing and adapting your structure is often also necessary. + +.. tip:: + Even if your documentation already has a structure, + we invite you to keep reading. + Changing a documentation structure is hard work, + but the rewards are big. One of the largest benefits of a good structure is that it removes questions that keep authors from writing documentation. Starting with a blank page is often the hardest part of documentation, so anything we can do to remove this problem is a win. -Recommendations for process ---------------------------- +Choosing a structure +-------------------- + +Good news! +You don't have to invent all of the structure yourself, +since a lot of experience-based work has been done to come up with a universal documentation structure. In order to avoid starting with a blank page, we recommend a simple process: From ee2be1a693c2e029300995f4d7858515c1a5c9d9 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 24 Feb 2023 20:31:13 +0100 Subject: [PATCH 05/34] Rename to "Continuous Documentation", it fits in one line and is a more precise concept --- docs/user/integrations.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/user/integrations.rst b/docs/user/integrations.rst index d27e3d39b86..e316a44bc6a 100644 --- a/docs/user/integrations.rst +++ b/docs/user/integrations.rst @@ -7,11 +7,13 @@ -Continuous Documentation Deployment -=================================== +Continuous Documentation +======================== -Read the Docs is a *Continuous Documentation Deployment* platform for your software project. -Every time you change something in your documentation, Read the Docs will detect your change and build your documentation. +Read the Docs is a *Continuous Documentation* platform for your software project. +Every time you change something in your documentation, Read the Docs will automatically detect your changes, +*build* your documentation, +and finally *deploy* your documentation for readers to see. The Continuous Integration and Continuous Deployment (CI/CD) features are configured with your repository provider, such as GitHub, Bitbucket or GitLab. From d51c79a009b6174bdbf75e38f3b2b32d3a0b0a20 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 24 Feb 2023 20:42:53 +0100 Subject: [PATCH 06/34] First quick take at introducing a dedicated documentation platform, should probably remove old content --- docs/user/choosing-a-site.rst | 37 ++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/docs/user/choosing-a-site.rst b/docs/user/choosing-a-site.rst index b964507b1ea..f97df7bab40 100644 --- a/docs/user/choosing-a-site.rst +++ b/docs/user/choosing-a-site.rst @@ -1,13 +1,36 @@ -Choosing between our two platforms -================================== +Choosing a dedicated documentation platform +=========================================== -Users often ask what the differences are between |org_brand| and |com_brand|. +Read the Docs is a *choice* that needs explanation and understanding. +The reasons behind choosing a dedicated platform for building and deploying your documentation is in fact our *vision* for Read the Docs. + +At the same time, users often ask what the differences are between |org_brand| and |com_brand|. + +Why choose a dedicated documentation platform? +---------------------------------------------- + +It's common to think that documentation is as simple as maintaining some content for a static website. Job done. +But once you get the full picture of how complex maintaining a documentation site is over time, +it will make sense to choose a platform that's based on decades of experience in operating documentation tools that have proven their value over the same span of time. + +A very straight-forward way to understand Read the Docs is to look at our :doc:`feature reference `. +All these features ultimately sustain the life-cycle of a documentation project. + +.. insert life-cycle diagram. + +Differences between Community and Business +------------------------------------------ While many of our features are available on both of these platforms, there are some key differences between our two platforms. -Read the Docs Community ------------------------ +.. seealso:: + + `Our website: Comparison of Community and all subscription plans `__ + Refer to the complete table of features included in all of the Read the Docs solutions available. + +|org_brand| +~~~~~~~~~~~ |org_brand| is exclusively for hosting open source documentation. We support open source communities by providing free documentation building and hosting @@ -25,8 +48,8 @@ Important points: You can sign up for an account at https://readthedocs.org. -Read the Docs for Business --------------------------- +|com_brand| +~~~~~~~~~~~ |com_brand| is meant for companies and users who have more complex requirements for their documentation project. This can include commercial projects with From 8add1b58b14d87555537b479d547e0fad0ff0b79 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 24 Feb 2023 23:23:09 +0100 Subject: [PATCH 07/34] WIP: marking an idea of a short and long version of process (needs potentially a diagram) --- docs/user/integrations.rst | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/user/integrations.rst b/docs/user/integrations.rst index e316a44bc6a..3c760169c90 100644 --- a/docs/user/integrations.rst +++ b/docs/user/integrations.rst @@ -20,7 +20,20 @@ such as GitHub, Bitbucket or GitLab. With each change committed to your repository, we are notified by the configured *webhook*. When a receive a *webhook* notification, we match it to a project's *Integration*. -When a webhook is received, the matching project will then: +When a webhook is received, the matching project will then process your setup and publish the documentation. + +The short version +----------------- + +If you follow for instance the tutorial, +a simple setup will use our builders and deploy everything in the following way: + +1. ... +2. ... +3. ... + +The long version +---------------- * :doc:`Build ` the latest commit. * Synchronize your versions based on the latest tag and branch data in Git. From 33533fbe10923c84e0e3ce37460ae52737e4b5ae Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Mon, 27 Mar 2023 17:06:22 +0200 Subject: [PATCH 08/34] Add a better outline of what the article should contain --- docs/user/choosing-a-site.rst | 67 +++++++++++++++++++++++++++++++---- 1 file changed, 60 insertions(+), 7 deletions(-) diff --git a/docs/user/choosing-a-site.rst b/docs/user/choosing-a-site.rst index f97df7bab40..08061a1c177 100644 --- a/docs/user/choosing-a-site.rst +++ b/docs/user/choosing-a-site.rst @@ -1,23 +1,76 @@ +.. This page seeks to put out lots of pointers to other articles in the documentation +.. while giving an introduction that can be read consecutively. + Choosing a dedicated documentation platform =========================================== -Read the Docs is a *choice* that needs explanation and understanding. -The reasons behind choosing a dedicated platform for building and deploying your documentation is in fact our *vision* for Read the Docs. +In this article, +we explain the major reasons behind having a platform dedicated to build and publish documentation projects. +In other words, +we dive into some of the reasons behind Read the Docs' existence and vision. + +Let us start with the major benefits of choosing a dedicated documentation platform: + +* Life-cycle: Handling challenges and complexities that documentation projects face +* Freedom to choose your documentation tools +* Workflow: Supportive of agile workflows and automating repetitive tasks + +When observing a documentation project, +we might understand documentation as simply one or more deliverables of the project, such as: +A website, a PDF document, an API documentation. +We might simply focus on choosing the software tools generate a static website or a set of :doc:`documentation output formats `. -At the same time, users often ask what the differences are between |org_brand| and |com_brand|. +Choosing to use Read the Docs as a first-step, +allows you to focus on other critical choices, +such as documentation tools and documentation structure. -Why choose a dedicated documentation platform? ----------------------------------------------- +Supporting the life-cycle of a documentation project +---------------------------------------------------- It's common to think that documentation is as simple as maintaining some content for a static website. Job done. -But once you get the full picture of how complex maintaining a documentation site is over time, -it will make sense to choose a platform that's based on decades of experience in operating documentation tools that have proven their value over the same span of time. +Read the Docs is a platform that's based on decades of experience in operating documentation tools that have proven their value over the same span of time. +It handles challenges that you might face down the road by having the right features ready when you need them. + +Example: Automated versioning and redirects + Once a documentation project is bootstrapped, + the software project might change its version and remove and add features. + Old versions of the project still need to be able to refer to their original documentation while new versions should not be unnecessarily complicated by documenting old features. + That is why Read the Docs supports versioning out-of-the-box and also gives you a mature set of options for creating automated redirects. + It's not just simple A=>B redirects, but they can follow your own patterns or work only on specific versions. + +Example: Analytics + Documentation websites also benefit from knowing which pages are popular and how people discover them through online search. + It would be understandable that this is not an immediate requirement for a documentation project, + but the need eventually arises, + and why should every documentation project have to implement their own analytics solution? A very straight-forward way to understand Read the Docs is to look at our :doc:`feature reference `. All these features ultimately sustain the life-cycle of a documentation project. .. insert life-cycle diagram. +Freedom to choose documentation tools +------------------------------------- + + +Agile workflows with Continuous Integration and Deployment (CI/CD) +------------------------------------------------------------------ + + +Types of documentation projects +------------------------------- + + +Software projects +~~~~~~~~~~~~~~~~~ + +... + +Scientific writing and academic projects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +... + Differences between Community and Business ------------------------------------------ From 17d5ba8559626caab76128415484d2ff8dd272ad Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Mon, 27 Mar 2023 19:08:36 +0200 Subject: [PATCH 09/34] Add a bit more copy --- docs/user/choosing-a-site.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/user/choosing-a-site.rst b/docs/user/choosing-a-site.rst index 08061a1c177..f39bb98c1bd 100644 --- a/docs/user/choosing-a-site.rst +++ b/docs/user/choosing-a-site.rst @@ -1,5 +1,6 @@ .. This page seeks to put out lots of pointers to other articles in the documentation .. while giving an introduction that can be read consecutively. +.. TODO: Links and references! Choosing a dedicated documentation platform =========================================== @@ -52,11 +53,18 @@ All these features ultimately sustain the life-cycle of a documentation project. Freedom to choose documentation tools ------------------------------------- +One of the big choices facing new documentation project is to choose between the many documentation tools that exist. +Read the Docs was originally built for Sphinx, +but has since then evolved into a generic documentation building platform. + +In the build process, +your documentation tool is called according to your own configuration and Read the Docs will then use the outputs to automatically publish your documentation website and offline formats. Agile workflows with Continuous Integration and Deployment (CI/CD) ------------------------------------------------------------------ + Types of documentation projects ------------------------------- From 99fd304cb2c2e0cd2fed9f7a3ce960c63bb22180 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 28 Mar 2023 17:02:22 +0200 Subject: [PATCH 10/34] WIP: Removes a lot of intentions and finishes first-draft of remaining sections. Some work still left. --- docs/user/choosing-a-site.rst | 136 +++++++++++++++++++++----- docs/user/explanation/advanced.rst | 15 +++ docs/user/explanation/diataxis.rst | 6 +- docs/user/explanation/methodology.rst | 18 +++- docs/user/integrations.rst | 33 ++++--- 5 files changed, 162 insertions(+), 46 deletions(-) diff --git a/docs/user/choosing-a-site.rst b/docs/user/choosing-a-site.rst index f39bb98c1bd..bf248805fe8 100644 --- a/docs/user/choosing-a-site.rst +++ b/docs/user/choosing-a-site.rst @@ -1,41 +1,82 @@ .. This page seeks to put out lots of pointers to other articles in the documentation .. while giving an introduction that can be read consecutively. -.. TODO: Links and references! +.. TODO: +.. - Links and references! +.. - Diagram in life-cycle section Choosing a dedicated documentation platform =========================================== In this article, -we explain the major reasons behind having a platform dedicated to build and publish documentation projects. +we introduce the major reasons behind having a dedicated platform for building and publishing documentation projects. In other words, we dive into some of the reasons behind Read the Docs' existence and vision. Let us start with the major benefits of choosing a dedicated documentation platform: -* Life-cycle: Handling challenges and complexities that documentation projects face -* Freedom to choose your documentation tools -* Workflow: Supportive of agile workflows and automating repetitive tasks +:ref:`lifecycle` + A dedicated documentation platform handles a variety of challenges and complexities that documentation projects face throughout their lifecycle. + +:ref:`documentation_tools` + By choosing a tool-agnostic dedicated platform, + you can use the documentation tools that you want. + +:ref:`workflows` + Publish your documentation automatically and version it together with your product. + Support for multiple versions and many different types of projects and workflows. + +Choosing to use Read the Docs as a first step, +allows you to focus on other critical tasks, +such as choosing documentation tools and structuring your documentation. +Not to mention *writing the documentation itself*! When observing a documentation project, we might understand documentation as simply one or more deliverables of the project, such as: A website, a PDF document, an API documentation. -We might simply focus on choosing the software tools generate a static website or a set of :doc:`documentation output formats `. +But in order to get there, +a dedicated documentation platform is a reliable first choice. +Such a platform helps to solve tasks that you otherwise end up writing and maintaining your own scripts and CI tools for. + +.. seealso:: + + `Comparison with GitHub Pages `__ + On our website, we have a list of common tasks that developers and DevOps teams have to solve themselves on a generic CI. + +.. Keeping this list commented out for now. +.. The seealso is better, since this is largely marketing content. +.. It's also nice to not break up the reading flow with a long list. Should delete... +.. * ✅️ Publishing a static website +.. * ✅️ Adding a fast cache layer for the website +.. * ✅️ Maintaining SSL +.. * ✅️ Notifications when things go wrong +.. * ✅️ Versioning +.. * ✅️ Letting users switch between versions +.. * ✅️ Offering additional formats (PDFs, ebooks) +.. * ✅️ Custom 404 pages +.. * ✅️ Building a fast search index +.. * ✅️ Having APIs to access documentation contents and integrate them elsewhere +.. * ✅️ Redirecting users that visit old URLs +.. * ✅️ Inviting a dedicated documentation team to manage all this +.. * ✅️ Manage access to private documentation projects +.. * ...this list is longer, and it is incidentally also the list of features that were built for Read the Docs. + +The role of a *dedicated documentation platform* is to offer the set of features that documentation projects and their organizations need. -Choosing to use Read the Docs as a first-step, -allows you to focus on other critical choices, -such as documentation tools and documentation structure. +Read the Docs does exactly this in two versions: +|org_brand| and |com_brand|. :ref:`Read more about their differences `. -Supporting the life-cycle of a documentation project ----------------------------------------------------- +.. _lifecycle: -It's common to think that documentation is as simple as maintaining some content for a static website. Job done. -Read the Docs is a platform that's based on decades of experience in operating documentation tools that have proven their value over the same span of time. -It handles challenges that you might face down the road by having the right features ready when you need them. +Features for the life-cycle of a documentation project +------------------------------------------------------ + +Read the Docs is a platform with over a decade of experience in automating documentation tools. +The platform handles challenges that you might face down the road by always having the right features ready when you need them. Example: Automated versioning and redirects Once a documentation project is bootstrapped, - the software project might change its version and remove and add features. - Old versions of the project still need to be able to refer to their original documentation while new versions should not be unnecessarily complicated by documenting old features. + the software product might change its version and remove and add features. + Old versions of the product still need to be able to refer to their original documentation while new versions should not be unnecessarily complicated by documenting old features. That is why Read the Docs supports versioning out-of-the-box and also gives you a mature set of options for creating automated redirects. It's not just simple A=>B redirects, but they can follow your own patterns or work only on specific versions. @@ -44,11 +85,15 @@ Example: Analytics It would be understandable that this is not an immediate requirement for a documentation project, but the need eventually arises, and why should every documentation project have to implement their own analytics solution? + For this, you can use :doc:`/reference/analytics`. A very straight-forward way to understand Read the Docs is to look at our :doc:`feature reference `. All these features ultimately sustain the life-cycle of a documentation project. .. insert life-cycle diagram. +.. new product + documentation project => new documentation pages => more product versions => more readers => more reader inputs => breaking changes => legacy product versions + +.. _documentation_tools: Freedom to choose documentation tools ------------------------------------- @@ -57,27 +102,64 @@ One of the big choices facing new documentation project is to choose between the Read the Docs was originally built for Sphinx, but has since then evolved into a generic documentation building platform. -In the build process, -your documentation tool is called according to your own configuration and Read the Docs will then use the outputs to automatically publish your documentation website and offline formats. +In the :doc:`build process `, +your documentation tool is called according to your own configuration and Read the Docs will then gather, version and publish files written by the documentation tool. +Whatever documentation tool you choose to build with, +your static website and additional :doc:`offline formats ` can be gathered and published at your project's :doc:`domain ` + +A documentation tool simply needs to be able to run on Linux inside a Docker container. +Most documentation frameworks will do this. +Some popular choices include: + +* Sphinx +* MkDocs +* Jupyter Book +* ...and any other tool that will install and run in a Docker container. +* + plugins/extensions for all of the above! + +.. _workflows: Agile workflows with Continuous Integration and Deployment (CI/CD) ------------------------------------------------------------------ +Automating your build and deploy process, +enables documentation writers to suggest changes, share previews, receive feedback and implement feedback quickly and iteratively. +Making your documentation project's workflow *agile* is supported by Read the Docs by: + +Example: Automatic Git integration + Many software projects already have a Git workflow, + while many other types of projects have recently discovered the benefits of using Git. + A dedicated documentation CI/CD +Example: Automatic previews + When someone opens a *pull request*, + Read the Docs will automatically build and display these changes, + allowing your workflow to continue undisturbed. + No need to email screenshots or attachments. + No need to upload a temporary version somewhere. -Types of documentation projects -------------------------------- +Example: Automatic deploys with version tagging + Read the Docs enables you to only have to do things once. + You can *tag* your new version in Git and then have Read the Docs automatically see your change and publish a new version, + keeping old versions active. + +.. seealso:: + :ref:`Diátaxis methodology ` + Having an agile workflow enables your documentation project to *grow organically*. + This is one of the core principles of the Diatáxis Methodology, + which presents a universal structure and agile workflow methodology for documentation projects. -Software projects -~~~~~~~~~~~~~~~~~ +.. Types of documentation projects +.. ------------------------------- -... +.. Software projects +.. ~~~~~~~~~~~~~~~~~ -Scientific writing and academic projects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. Scientific writing and academic projects +.. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -... +.. _com_org_differences: Differences between Community and Business ------------------------------------------ @@ -131,7 +213,7 @@ Important points: You can sign up for an account at https://readthedocs.com. Questions? ----------- +~~~~~~~~~~ If you have a question about which platform would be best, email us at support@readthedocs.org. diff --git a/docs/user/explanation/advanced.rst b/docs/user/explanation/advanced.rst index d009b2e47c9..e82a23ab967 100644 --- a/docs/user/explanation/advanced.rst +++ b/docs/user/explanation/advanced.rst @@ -1,6 +1,21 @@ Deep dive into Read the Docs ============================ +In this section, +we explain some of the more specific or advanced concepts of writing documentation on Read the Docs. + +⏩️ :doc:`/downloadable-documentation` + TBD + +⏩️ :doc:`/environment-variables` + TBD + +⏩️ :doc:`/subprojects` + TBD + +⏩️ :doc:`/localization` + TBD + .. toctree:: :maxdepth: 2 diff --git a/docs/user/explanation/diataxis.rst b/docs/user/explanation/diataxis.rst index c984f68dbd8..9fe10790aa4 100644 --- a/docs/user/explanation/diataxis.rst +++ b/docs/user/explanation/diataxis.rst @@ -35,8 +35,10 @@ we recommend a simple process: This process helps you get started quickly, and helps keep things consistent for the reader of your documentation. -Diátaxis --------- +.. _diataxis: + +Diátaxis Methodology +-------------------- The documentation you're reading is written using the Diátaxis framework. It has four major parts as summarized by this image: diff --git a/docs/user/explanation/methodology.rst b/docs/user/explanation/methodology.rst index 98fb55a8628..fb12997a153 100644 --- a/docs/user/explanation/methodology.rst +++ b/docs/user/explanation/methodology.rst @@ -9,15 +9,27 @@ We encourage that you read this at any time, as each section gives approaches regardless of whether you need to create new content or restructure larger documentation sets. -:doc:`The Diátaxis Methodology ` +⏩️ :doc:`The Diátaxis Methodology ` In order to understand documentation in the most general and fundamental sense, we introduce the Diátaxis methodology which is also used for the documentation you are now reading. -Best practice: Search Engine Optimization - It's important that your documentation can be found using search engines. +.. TODO: The below content is from how-to guides, we need to figure out the duplication of text here. + +⏩️ :doc:`Creating reproducible builds ` + Every documentation project has dependencies that are required to build it. + Using an unspecified versions of these dependencies means that your project can start breaking. + In this guide, + learn how to protect your project against breaking randomly. + **This is one of our most popular guides!** + +⏩️ :doc:`Search Engine Optimization (SEO) for documentation projects ` + This article explains how documentation can be optimized to appear in search results, + increasing traffic to your docs. + .. toctree:: :maxdepth: 2 :hidden: diataxis + /guides/best-practice/index diff --git a/docs/user/integrations.rst b/docs/user/integrations.rst index 3c760169c90..57e80f749a4 100644 --- a/docs/user/integrations.rst +++ b/docs/user/integrations.rst @@ -22,24 +22,24 @@ With each change committed to your repository, we are notified by the configured When a receive a *webhook* notification, we match it to a project's *Integration*. When a webhook is received, the matching project will then process your setup and publish the documentation. -The short version ------------------ +.. The short version +.. ----------------- -If you follow for instance the tutorial, -a simple setup will use our builders and deploy everything in the following way: +.. If you follow for instance the tutorial, +.. a simple setup will use our builders and deploy everything in the following way: -1. ... -2. ... -3. ... +.. 1. ... +.. 2. ... +.. 3. ... -The long version ----------------- +.. The long version +.. ---------------- -* :doc:`Build ` the latest commit. -* Synchronize your versions based on the latest tag and branch data in Git. -* Run your :doc:`automation rules`. -* Auto-cancel any currently running builds of the same version. -* Add a log entry to the integration's :guilabel:`Recent Activity`. +.. * :doc:`Build ` the latest commit. +.. * Synchronize your versions based on the latest tag and branch data in Git. +.. * Run your :doc:`automation rules`. +.. * Auto-cancel any currently running builds of the same version. +.. * Add a log entry to the integration's :guilabel:`Recent Activity`. Continuous Documentation for software projects ---------------------------------------------- @@ -58,6 +58,11 @@ and increases overall value from the documentation you write. As part of this quick feedback loop, You can preview documentation changes immediately using :doc:`pull request previews `. +.. Continuous Documentation for scientific projects +.. ------------------------------------------------ + +.. We should perhaps write a short introduction here and reference the science page. + Automated versioning -------------------- From 5b4faf46cf0a18c512c31a8b4452332e01578c52 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 28 Mar 2023 22:26:28 +0200 Subject: [PATCH 11/34] Lots of changes, including removal of /choosing-a-site and /integrations --- docs/user/connected-accounts.rst | 6 +- docs/user/explanation/advanced.rst | 22 ++--- .../continuous-documentation.rst} | 0 .../dedicated-platform.rst} | 90 ++++++++++++------- ...ataxis.rst => documentation-structure.rst} | 0 docs/user/explanation/methodology.rst | 11 ++- docs/user/flyout-menu.rst | 2 +- docs/user/glossary.rst | 8 ++ .../guides/importing-private-repositories.rst | 4 +- docs/user/index.rst | 14 +-- docs/user/tutorial/index.rst | 4 +- docs/user/versions.rst | 2 +- 12 files changed, 103 insertions(+), 60 deletions(-) rename docs/user/{integrations.rst => explanation/continuous-documentation.rst} (100%) rename docs/user/{choosing-a-site.rst => explanation/dedicated-platform.rst} (67%) rename docs/user/explanation/{diataxis.rst => documentation-structure.rst} (100%) diff --git a/docs/user/connected-accounts.rst b/docs/user/connected-accounts.rst index 5300b2fe590..062b5e7762a 100644 --- a/docs/user/connected-accounts.rst +++ b/docs/user/connected-accounts.rst @@ -19,8 +19,8 @@ we recommend that you connect your Read the Docs account to your Git provider. Connecting your account allows for: * Easy import of your repositories. -* Automatic configuration of your repository :doc:`/integrations`. - which allow Read the Docs to build your docs on every change to your repository +* Automatic configuration of your repository's :term:`webhooks`. + which allows Read the Docs to build your docs on every change to your repository. * Logging into Read the Docs with your |git_providers_or| credentials. @@ -71,7 +71,7 @@ Read the Docs does not generally ask for *write* permission to your repository c and since we only connect to public repositories we don't need special permissions to read them. However, we do need permissions for authorizing your account so that you can login to Read the Docs with your connected account credentials -and to setup :doc:`/integrations` +and to setup :term:`webhooks` which allow us to build your documentation on every change to your repository. diff --git a/docs/user/explanation/advanced.rst b/docs/user/explanation/advanced.rst index e82a23ab967..d4daaa02d13 100644 --- a/docs/user/explanation/advanced.rst +++ b/docs/user/explanation/advanced.rst @@ -4,24 +4,26 @@ Deep dive into Read the Docs In this section, we explain some of the more specific or advanced concepts of writing documentation on Read the Docs. -⏩️ :doc:`/downloadable-documentation` - TBD - -⏩️ :doc:`/environment-variables` - TBD - ⏩️ :doc:`/subprojects` - TBD + Thinking about gathering several documentation projects under the same umbrella? + This is a common need, and using *subprojects* is a flexible option that is recommended for most cases. ⏩️ :doc:`/localization` - TBD + Learn more about multilingual documentation projects and how translation workflows are supported. + +⏩️ :doc:`/downloadable-documentation` + An introduction to adding downloadable files to your documentation and keep them versioned. + +⏩️ :doc:`/environment-variables` + Environment variables can be used to make your documentation builds flexible and easy to customize. + Here are some reasons why you may or may not want to use them. .. toctree:: :maxdepth: 2 :hidden: - /downloadable-documentation - /environment-variables /subprojects /localization + /downloadable-documentation + /environment-variables diff --git a/docs/user/integrations.rst b/docs/user/explanation/continuous-documentation.rst similarity index 100% rename from docs/user/integrations.rst rename to docs/user/explanation/continuous-documentation.rst diff --git a/docs/user/choosing-a-site.rst b/docs/user/explanation/dedicated-platform.rst similarity index 67% rename from docs/user/choosing-a-site.rst rename to docs/user/explanation/dedicated-platform.rst index bf248805fe8..df949b9fd9f 100644 --- a/docs/user/choosing-a-site.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -3,47 +3,63 @@ .. TODO: .. - Links and references! .. - Diagram in life-cycle section +.. +.. There are other reasons that we could cover: +.. - Code: If you write docs as code, you want this +.. - When you should NOT choose a dedicated documentation CI/CD: You just need a README in your Git repo! You need WYSIWYG so badly that you're probably better off with Confluence, GitBook or Google Docs. +.. - A dedicated platform helps to solve tasks that you otherwise end up writing and maintaining your own scripts and CI tools for. +.. - Always evolving: Read the Docs develops new features on-demand. So you get a dedicated platform that's maintained and has new features added. +.. - Community: Related to the above, but perhaps worth mentioning that a lot of people are building tools and extensions that run on the platform etc. +.. - Batteries included / integrations: Flyout menu, search, SSL certificate Choosing a dedicated documentation platform =========================================== -In this article, -we introduce the major reasons behind having a dedicated platform for building and publishing documentation projects. +This is an introduction to the most common benefits of choosing a dedicated platform for building and publishing documentation projects. In other words, we dive into some of the reasons behind Read the Docs' existence and vision. -Let us start with the major benefits of choosing a dedicated documentation platform: +Let us start with a high-level overview: -:ref:`lifecycle` - A dedicated documentation platform handles a variety of challenges and complexities that documentation projects face throughout their lifecycle. +🧭️️️ :ref:`lifecycle` + A dedicated documentation platform has all the features to handle a variety of challenges and complexities that documentation projects meet during their lifecycle. -:ref:`documentation_tools` +🛠️ :ref:`documentation_tools` By choosing a tool-agnostic dedicated platform, you can use the documentation tools that you want. -:ref:`workflows` - Publish your documentation automatically and version it together with your product. +🚢️️ :ref:`workflows` + A dedicated CI/CD platform publishes your documentation automatically and versions it so you can focus on applying your own workflow and keep the documentation aligned with your product. Support for multiple versions and many different types of projects and workflows. -Choosing to use Read the Docs as a first step, +.. The following sections are about using a dedicated platform as a first-choice in order to free up space for other tasks. +.. These paragraphs can benefit from being shortened and organized, but they are intended as the summary of the introduction. + +Using Read the Docs allows you to focus on other critical tasks, -such as choosing documentation tools and structuring your documentation. +such as choosing documentation tools, structuring your documentation and having the perfect workflow. Not to mention *writing the documentation itself*! -When observing a documentation project, -we might understand documentation as simply one or more deliverables of the project, such as: -A website, a PDF document, an API documentation. +If we observe a documentation project simply from the outside, +we might only see the documentation as one or more deliverables, such as: +A website, a PDF document, or an API documentation. But in order to get there, a dedicated documentation platform is a reliable first choice. -Such a platform helps to solve tasks that you otherwise end up writing and maintaining your own scripts and CI tools for. + +A dedicated platform helps to solve tasks that you otherwise end up writing and maintaining your own scripts and CI tools for. .. seealso:: `Comparison with GitHub Pages `__ On our website, we have a list of common tasks that developers and DevOps teams have to solve themselves on a generic CI. +Simply put, the role of a *dedicated documentation platform* is to offer a compelling set of features that documentation projects and their organizations or communities need. + +Read the Docs does exactly this in two versions: +|org_brand| and |com_brand|. :ref:`Read more about their differences `. + .. Keeping this list commented out for now. -.. The seealso is better, since this is largely marketing content. +.. The seealso about GitHub pages is better, since this is largely marketing content. .. It's also nice to not break up the reading flow with a long list. Should delete... .. * ✅️ Publishing a static website .. * ✅️ Adding a fast cache layer for the website @@ -60,18 +76,13 @@ Such a platform helps to solve tasks that you otherwise end up writing and maint .. * ✅️ Manage access to private documentation projects .. * ...this list is longer, and it is incidentally also the list of features that were built for Read the Docs. -The role of a *dedicated documentation platform* is to offer the set of features that documentation projects and their organizations need. - -Read the Docs does exactly this in two versions: -|org_brand| and |com_brand|. :ref:`Read more about their differences `. - .. _lifecycle: -Features for the life-cycle of a documentation project ------------------------------------------------------- +Features for the lifecycle of a documentation project +----------------------------------------------------- Read the Docs is a platform with over a decade of experience in automating documentation tools. -The platform handles challenges that you might face down the road by always having the right features ready when you need them. +The platform handles challenges that you might face down the road by having the right features ready when you need them. Example: Automated versioning and redirects Once a documentation project is bootstrapped, @@ -87,8 +98,11 @@ Example: Analytics and why should every documentation project have to implement their own analytics solution? For this, you can use :doc:`/reference/analytics`. -A very straight-forward way to understand Read the Docs is to look at our :doc:`feature reference `. -All these features ultimately sustain the life-cycle of a documentation project. +.. seealso:: + + :doc:`/reference/features` + A practical way to understand Read the Docs is to look at our :doc:`list of features `. + All these features ultimately sustain the life-cycle of a documentation project. .. insert life-cycle diagram. .. new product + documentation project => new documentation pages => more product versions => more readers => more reader inputs => breaking changes => legacy product versions @@ -105,31 +119,40 @@ but has since then evolved into a generic documentation building platform. In the :doc:`build process `, your documentation tool is called according to your own configuration and Read the Docs will then gather, version and publish files written by the documentation tool. Whatever documentation tool you choose to build with, -your static website and additional :doc:`offline formats ` can be gathered and published at your project's :doc:`domain ` +your static website and additional :doc:`offline formats ` can be versioned and published at your project's :doc:`domain ` A documentation tool simply needs to be able to run on Linux inside a Docker container. Most documentation frameworks will do this. Some popular choices include: +.. TODO: expand the list and add links + * Sphinx * MkDocs * Jupyter Book * ...and any other tool that will install and run in a Docker container. -* + plugins/extensions for all of the above! +* ...and plugins/extensions for all of the above! .. _workflows: Agile workflows with Continuous Integration and Deployment (CI/CD) ------------------------------------------------------------------ -Automating your build and deploy process, +Automating your `build and deploy process `, enables documentation writers to suggest changes, share previews, receive feedback and implement feedback quickly and iteratively. -Making your documentation project's workflow *agile* is supported by Read the Docs by: +Making your documentation project's workflow *agile* is supported by Read the Docs through a number of features. +Here are some examples: + +.. these examples need more love. They could be more focused on practical tasks, rather than just the abstract topic. Example: Automatic Git integration Many software projects already have a Git workflow, while many other types of projects have recently discovered the benefits of using Git. - A dedicated documentation CI/CD + A dedicated documentation CI/CD will hook into your Git repository and be notified of changes so it can build and publish your documentation. + This includes a number of additional options, + such as support for private repositories, + storing Read the Docs configuration in the Git repository (configuration as code) + and managing access through GitHub SSO. Example: Automatic previews When someone opens a *pull request*, @@ -145,6 +168,9 @@ Example: Automatic deploys with version tagging .. seealso:: + :doc:`/explanation/continuous-documentation` + A more technical introduction to CI/CD for documentation projects. + :ref:`Diátaxis methodology ` Having an agile workflow enables your documentation project to *grow organically*. This is one of the core principles of the Diatáxis Methodology, @@ -175,8 +201,8 @@ are some key differences between our two platforms. |org_brand| ~~~~~~~~~~~ -|org_brand| is exclusively for hosting open source documentation. We support -open source communities by providing free documentation building and hosting +|org_brand| is exclusively for free and open source software, content and projects. +We support open source communities by providing free documentation building and hosting services, for projects of all sizes. Important points: diff --git a/docs/user/explanation/diataxis.rst b/docs/user/explanation/documentation-structure.rst similarity index 100% rename from docs/user/explanation/diataxis.rst rename to docs/user/explanation/documentation-structure.rst diff --git a/docs/user/explanation/methodology.rst b/docs/user/explanation/methodology.rst index fb12997a153..653b632139a 100644 --- a/docs/user/explanation/methodology.rst +++ b/docs/user/explanation/methodology.rst @@ -4,12 +4,19 @@ Methodology and best practice In this section, we are covering important methods and best practices that will make your documentation better. +.. seealso:: + + `Write the Docs: Content Archive `__ + Did you know that Read the Docs is related to `Write the Docs `__? + Write the Docs is a conference, a community and a documentation project that's full of methods, tips and + articles about writing documentation. + You can familiarize yourself with these topics before or after writing documentation. We encourage that you read this at any time, as each section gives approaches regardless of whether you need to create new content or restructure larger documentation sets. -⏩️ :doc:`The Diátaxis Methodology ` +⏩️ :doc:`The Diátaxis Methodology ` In order to understand documentation in the most general and fundamental sense, we introduce the Diátaxis methodology which is also used for the documentation you are now reading. @@ -31,5 +38,5 @@ regardless of whether you need to create new content or restructure larger docum :maxdepth: 2 :hidden: - diataxis + documentation-structure /guides/best-practice/index diff --git a/docs/user/flyout-menu.rst b/docs/user/flyout-menu.rst index 640c51701bb..072b815a5b1 100644 --- a/docs/user/flyout-menu.rst +++ b/docs/user/flyout-menu.rst @@ -14,7 +14,7 @@ The flyout menu provides access to the following bits of Read the Docs functiona * A :doc:`version switcher ` that shows users all of the active, unhidden versions they have access to. * :doc:`Offline formats ` for the current version, including HTML & PDF downloads that are enabled by the project. * Links to the Read the Docs dashboard for the project. -* Links to your :doc:`VCS provider ` that allow the user to quickly find the exact file that the documentation was rendered from. +* Links to your Git provider (|git_providers_or|) that allow the user to quickly find the exact file that the documentation was rendered from. * A search bar that gives users access to our :doc:`/server-side-search/index` of the current version. Closed diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst index 6491bdf4a12..0ae31f23737 100644 --- a/docs/user/glossary.rst +++ b/docs/user/glossary.rst @@ -39,6 +39,14 @@ so that you have a reference for how we're using them. and rules for publication of documentation can be :doc:`automated `. Similar to :term:`Docs as Code`. + webhooks + There are two important types of webhooks for Read the Docs: + + * Git providers have webhooks which are special URLs that Read the Docs can call in order to notify about documentation builds. + * Read the Docs has a unique webhook for each project that the Git provider calls when changes happen in Git. + + See also: :doc:`/guides/git-integrations` and :doc:`/build-notifications` + pre-defined build jobs Commands executed by Read the Docs when performing the build process. They cannot be overwritten by the user. diff --git a/docs/user/guides/importing-private-repositories.rst b/docs/user/guides/importing-private-repositories.rst index f5bd09f916f..ad63df98a22 100644 --- a/docs/user/guides/importing-private-repositories.rst +++ b/docs/user/guides/importing-private-repositories.rst @@ -4,7 +4,7 @@ How to import private repositories .. warning:: This guide is for users of :doc:`/commercial/index`. - **If you are using GitHub, GitLab, or Bitbucket**, + **If you are using |git_providers_or|**, we recommend :doc:`connecting your account ` and importing your project from https://readthedocs.com/dashboard/import instead of importing it manually. @@ -122,7 +122,7 @@ Webhooks -------- To build your documentation on every commit, -you'll need to manually add a webhook, see :doc:`/integrations`. +you'll need to manually add a webhook, see :doc:`/guides/git-integrations`. If you are using an unsupported integration, you may need to setup a custom integration using our :ref:`generic webhook `. diff --git a/docs/user/index.rst b/docs/user/index.rst index 67ab69f13a4..1800e9122f6 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -17,8 +17,8 @@ Read the Docs: documentation simplified :hidden: :caption: 💡 Explanation - /choosing-a-site - /integrations + /explanation/dedicated-platform + /explanation/continuous-documentation /explanation/methodology /explanation/advanced @@ -83,7 +83,7 @@ and your documentation up to date. |org_brand| hosts documentation for over 100,000 large and small open source projects. |com_brand| supports hundreds of organizations with product and internal documentation. - Learn more about :doc:`our two platforms `. + Learn more about :ref:`our two platforms `. First time here? ---------------- @@ -118,11 +118,11 @@ Get a high-level overview of our platform: .. TODO: This next item needs its article to be finished in a separate PR .. https://github.com/readthedocs/readthedocs.org/pull/10071 -💡 :doc:`Continuous Documentation ` - Discover the advantages of having your documentation continuously deployed. +💡 :doc:`/explanation/dedicated-platform` + An introduction to using a dedicated documentation platform. -💡 :doc:`/choosing-a-site` - Learn about the differences between |org_brand| and |com_brand|. +💡 :doc:`/explanation/continuous-documentation` + Discover the advantages of having your documentation continuously deployed. .. TODO: This next item needs its article to be finished in a separate PR .. https://github.com/readthedocs/readthedocs.org/pull/10071 diff --git a/docs/user/tutorial/index.rst b/docs/user/tutorial/index.rst index d27c35f0223..2f0caa0113d 100644 --- a/docs/user/tutorial/index.rst +++ b/docs/user/tutorial/index.rst @@ -112,7 +112,7 @@ Welcome! Our commercial site offers some extra features, like support for private projects. - You can learn more about :doc:`our two different sites `. + You can learn more about :ref:`our two platforms `. First steps ----------- @@ -675,7 +675,7 @@ and Read the Docs: available under :doc:`/guides/index`. - For private project support and other enterprise features, you can use :doc:`our commercial service ` - (and if in doubt, check out :doc:`/choosing-a-site`). + (and if in doubt, check out :ref:`com_org_differences`). - Do you want to join a global community of fellow `documentarians `? Check out `Write the Docs `_ and :doc:`its Slack workspace `. diff --git a/docs/user/versions.rst b/docs/user/versions.rst index a20c7f994d4..3efed05bd5f 100644 --- a/docs/user/versions.rst +++ b/docs/user/versions.rst @@ -12,7 +12,7 @@ we also create a ``stable`` version, tracking your most recent release. If you want a custom ``stable`` version, create either a tag or branch in your project with that name. -When you have :doc:`/integrations` configured for your repository, +When you have :term:`webhooks` configured for your repository, we will automatically build each version when you push a commit. How we envision versions working From 86260539bf5f768b8de9294f82c03253ce5a6c87 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 28 Mar 2023 22:41:37 +0200 Subject: [PATCH 12/34] We should also say "Read the Docs" --- docs/user/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/index.rst b/docs/user/index.rst index 1800e9122f6..449ebd5191e 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -119,7 +119,7 @@ Get a high-level overview of our platform: .. https://github.com/readthedocs/readthedocs.org/pull/10071 💡 :doc:`/explanation/dedicated-platform` - An introduction to using a dedicated documentation platform. + An introduction the reasons behind choosing a dedicated documentation platform such as Read the Docs. 💡 :doc:`/explanation/continuous-documentation` Discover the advantages of having your documentation continuously deployed. From 4b4c2a72430a7b5e1b3c30cb3c44b931f5896316 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 28 Mar 2023 23:33:45 +0200 Subject: [PATCH 13/34] =?UTF-8?q?Improve=20the=20examples=20in=20Features?= =?UTF-8?q?=20for=20the=20lifecycle=20of=20a=20documentation=20project?= =?UTF-8?q?=EF=83=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/user/explanation/dedicated-platform.rst | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index df949b9fd9f..199fd2beeaf 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -82,20 +82,24 @@ Features for the lifecycle of a documentation project ----------------------------------------------------- Read the Docs is a platform with over a decade of experience in automating documentation tools. -The platform handles challenges that you might face down the road by having the right features ready when you need them. +The platform handles your current challenges or challenges that you face down the road. +The right features are available when you need them. Example: Automated versioning and redirects Once a documentation project is bootstrapped, - the software product might change its version and remove and add features. + the software product might change its version and remove or add features. Old versions of the product still need to be able to refer to their original documentation while new versions should not be unnecessarily complicated by documenting old features. - That is why Read the Docs supports versioning out-of-the-box and also gives you a mature set of options for creating automated redirects. - It's not just simple A=>B redirects, but they can follow your own patterns or work only on specific versions. + + That is why Read the Docs supports versioning out-of-the-box and also gives you a mature set of options for creating :doc:`user-defined redirects `. + + As your documentation grows and pages are moved around, versioning and redirects become critical. Example: Analytics - Documentation websites also benefit from knowing which pages are popular and how people discover them through online search. - It would be understandable that this is not an immediate requirement for a documentation project, - but the need eventually arises, - and why should every documentation project have to implement their own analytics solution? + Documentation websites benefit from knowing which pages are popular and how people discover them through online search. + + This may not be an immediate requirement for a documentation project, + but the need often arises. + And why should every documentation project have to implement their own analytics solution? For this, you can use :doc:`/reference/analytics`. .. seealso:: From ef44e2569be48cc145c3c8bda755893ac26900a2 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 28 Mar 2023 23:48:36 +0200 Subject: [PATCH 14/34] Remove a dangling sentence --- docs/user/explanation/dedicated-platform.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index 199fd2beeaf..3149ea53f1b 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -30,7 +30,6 @@ Let us start with a high-level overview: 🚢️️ :ref:`workflows` A dedicated CI/CD platform publishes your documentation automatically and versions it so you can focus on applying your own workflow and keep the documentation aligned with your product. - Support for multiple versions and many different types of projects and workflows. .. The following sections are about using a dedicated platform as a first-choice in order to free up space for other tasks. .. These paragraphs can benefit from being shortened and organized, but they are intended as the summary of the introduction. From f83abb8f49a2fd988ab44912e0ab77a895759fed Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 28 Mar 2023 23:50:59 +0200 Subject: [PATCH 15/34] Add term reference --- docs/user/explanation/continuous-documentation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/explanation/continuous-documentation.rst b/docs/user/explanation/continuous-documentation.rst index 57e80f749a4..040161537ad 100644 --- a/docs/user/explanation/continuous-documentation.rst +++ b/docs/user/explanation/continuous-documentation.rst @@ -17,7 +17,7 @@ and finally *deploy* your documentation for readers to see. The Continuous Integration and Continuous Deployment (CI/CD) features are configured with your repository provider, such as GitHub, Bitbucket or GitLab. -With each change committed to your repository, we are notified by the configured *webhook*. +With each change committed to your repository, we are notified by the configured :term:`webhook `. When a receive a *webhook* notification, we match it to a project's *Integration*. When a webhook is received, the matching project will then process your setup and publish the documentation. From 2c45f4ce3a45ee1f29fd79fbe28c24ae76617119 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 28 Mar 2023 23:54:12 +0200 Subject: [PATCH 16/34] =?UTF-8?q?Some=20texts=20dangling=20in=20Continuous?= =?UTF-8?q?=20Documentation=EF=83=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/user/explanation/continuous-documentation.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/user/explanation/continuous-documentation.rst b/docs/user/explanation/continuous-documentation.rst index 040161537ad..4e0f97bcf32 100644 --- a/docs/user/explanation/continuous-documentation.rst +++ b/docs/user/explanation/continuous-documentation.rst @@ -19,8 +19,13 @@ The Continuous Integration and Continuous Deployment (CI/CD) features are config such as GitHub, Bitbucket or GitLab. With each change committed to your repository, we are notified by the configured :term:`webhook `. -When a receive a *webhook* notification, we match it to a project's *Integration*. -When a webhook is received, the matching project will then process your setup and publish the documentation. +When a receive a *webhook* notification, we match it to a Read the Docs project. +The matching project will then process your build and publish the documentation. + +.. seealso:: + + :doc:`/builds` + Read more about the technical specification of the Build process and how you configure it. .. The short version .. ----------------- From 0605a441a4715845239440bfe295db614f82121a Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 28 Mar 2023 23:55:31 +0200 Subject: [PATCH 17/34] Big TODO here --- docs/user/explanation/continuous-documentation.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/user/explanation/continuous-documentation.rst b/docs/user/explanation/continuous-documentation.rst index 4e0f97bcf32..3b0c04aa17d 100644 --- a/docs/user/explanation/continuous-documentation.rst +++ b/docs/user/explanation/continuous-documentation.rst @@ -49,6 +49,8 @@ The matching project will then process your build and publish the documentation. Continuous Documentation for software projects ---------------------------------------------- +.. TODO: This should be improved + Documentation fits into any CI/CD pipeline by following a process known as *Documentation as Code (Docs as code)*. The primary method of doing this is by maintaining documentation alongside the source code, meaning that the documentation's life cycle is the same as your software project. From 5d3d4c51a087082d5db15af93dae857911c8368d Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 6 Apr 2023 15:29:07 +0200 Subject: [PATCH 18/34] Add quick intros to "Deep Dive into Read the Docs" --- docs/user/environment-variables.rst | 4 ++-- docs/user/explanation/advanced.rst | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/user/environment-variables.rst b/docs/user/environment-variables.rst index 5b523bf8346..266e4079d47 100644 --- a/docs/user/environment-variables.rst +++ b/docs/user/environment-variables.rst @@ -4,11 +4,11 @@ Understanding environment variables =================================== Read the Docs allows you to define your own environment variables to be used in the build process. -It also defines a set of :doc:`default environment variables ` with information about your build. +It also defines a set of :doc:`pre-defined environment variables ` with information about your build. These are useful for different purposes: * Custom environment variables are useful for adding build secrets such as API tokens. -* Default environment variables are useful for varying your build specifically for Read the Docs or specific types of builds on Read the Docs. +* Pre-defined environment variables are useful for varying your build specifically for Read the Docs or specific types of builds on Read the Docs. .. The following introduction is difficult to balance. .. We should ideally support environment variables in the Config File, diff --git a/docs/user/explanation/advanced.rst b/docs/user/explanation/advanced.rst index e82a23ab967..83a97faf4e3 100644 --- a/docs/user/explanation/advanced.rst +++ b/docs/user/explanation/advanced.rst @@ -5,16 +5,16 @@ In this section, we explain some of the more specific or advanced concepts of writing documentation on Read the Docs. ⏩️ :doc:`/downloadable-documentation` - TBD + An overview of a core Read the Docs feature: building docs in multiple formats. ⏩️ :doc:`/environment-variables` - TBD + A general introduction to environment variables on our platform, both pre-defined and custom environment variables. ⏩️ :doc:`/subprojects` - TBD + Learn more about how several documentation projects can be combined and presented to the reader on the same website. ⏩️ :doc:`/localization` - TBD + An introduction to internationalizing and localizing your documentation. .. toctree:: From 6b597adf6d872c17c9a740fa6904e32c1dded25c Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 6 Apr 2023 15:36:20 +0200 Subject: [PATCH 19/34] Split out methodology section to separate PR --- docs/user/explanation/dedicated-platform.rst | 2 +- .../explanation/documentation-structure.rst | 58 ------------------- docs/user/explanation/methodology.rst | 42 -------------- docs/user/index.rst | 1 - 4 files changed, 1 insertion(+), 102 deletions(-) delete mode 100644 docs/user/explanation/documentation-structure.rst delete mode 100644 docs/user/explanation/methodology.rst diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index 3149ea53f1b..4ac39ab097b 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -174,7 +174,7 @@ Example: Automatic deploys with version tagging :doc:`/explanation/continuous-documentation` A more technical introduction to CI/CD for documentation projects. - :ref:`Diátaxis methodology ` + `Diátaxis Framework `__ Having an agile workflow enables your documentation project to *grow organically*. This is one of the core principles of the Diatáxis Methodology, which presents a universal structure and agile workflow methodology for documentation projects. diff --git a/docs/user/explanation/documentation-structure.rst b/docs/user/explanation/documentation-structure.rst deleted file mode 100644 index 9fe10790aa4..00000000000 --- a/docs/user/explanation/documentation-structure.rst +++ /dev/null @@ -1,58 +0,0 @@ -How to structure your documentation -=================================== - -A documentation project's ultimate goal is to be read and understood by a reader. -Readers need to be able to :term:`discover ` the information that they need. -Without an intuitive structure, -readers either won't find information that they need or get frustrated on the way. -Having a structure in mind can happen from the very beginning of a documentation project. -Changing and adapting your structure is often also necessary. - -.. tip:: - Even if your documentation already has a structure, - we invite you to keep reading. - Changing a documentation structure is hard work, - but the rewards are big. - -One of the largest benefits of a good structure is that it removes questions that keep authors from writing documentation. -Starting with a blank page is often the hardest part of documentation, -so anything we can do to remove this problem is a win. - -Choosing a structure --------------------- - -Good news! -You don't have to invent all of the structure yourself, -since a lot of experience-based work has been done to come up with a universal documentation structure. - -In order to avoid starting with a blank page, -we recommend a simple process: - -* Choose a structure for your documentation. We recommend `Diátaxis `_ for this. -* Find a :doc:`example project ` or template to start from. -* Start writing by filling in the structure. - -This process helps you get started quickly, -and helps keep things consistent for the reader of your documentation. - -.. _diataxis: - -Diátaxis Methodology --------------------- - -The documentation you're reading is written using the Diátaxis framework. -It has four major parts as summarized by this image: - -.. image:: https://diataxis.fr/_images/diataxis.png - -We recommend that you read more about Diátaxis in the `documentation `_ for it. - -Explaining the structure to your users --------------------------------------- - -One of the benefits of Diátaxis is that it's a well-known structure, -and users might already be familiar with it. -As long as you stick to the structure, -your users should be able to use existing experience to navigate. - -Using the names that are defined (eg. Tutorials, Explanation) in a user-facing way also helps here. diff --git a/docs/user/explanation/methodology.rst b/docs/user/explanation/methodology.rst deleted file mode 100644 index 653b632139a..00000000000 --- a/docs/user/explanation/methodology.rst +++ /dev/null @@ -1,42 +0,0 @@ -Methodology and best practice -============================= - -In this section, -we are covering important methods and best practices that will make your documentation better. - -.. seealso:: - - `Write the Docs: Content Archive `__ - Did you know that Read the Docs is related to `Write the Docs `__? - Write the Docs is a conference, a community and a documentation project that's full of methods, tips and - articles about writing documentation. - -You can familiarize yourself with these topics before or after writing documentation. -We encourage that you read this at any time, -as each section gives approaches -regardless of whether you need to create new content or restructure larger documentation sets. - -⏩️ :doc:`The Diátaxis Methodology ` - In order to understand documentation in the most general and fundamental sense, - we introduce the Diátaxis methodology which is also used for the documentation you are now reading. - -.. TODO: The below content is from how-to guides, we need to figure out the duplication of text here. - -⏩️ :doc:`Creating reproducible builds ` - Every documentation project has dependencies that are required to build it. - Using an unspecified versions of these dependencies means that your project can start breaking. - In this guide, - learn how to protect your project against breaking randomly. - **This is one of our most popular guides!** - -⏩️ :doc:`Search Engine Optimization (SEO) for documentation projects ` - This article explains how documentation can be optimized to appear in search results, - increasing traffic to your docs. - - -.. toctree:: - :maxdepth: 2 - :hidden: - - documentation-structure - /guides/best-practice/index diff --git a/docs/user/index.rst b/docs/user/index.rst index 30cc2f21c59..8bb2782e890 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -19,7 +19,6 @@ Read the Docs: documentation simplified /explanation/dedicated-platform /explanation/continuous-documentation - /explanation/methodology /explanation/advanced .. toctree:: From bf1eb492d86c1d41fcb2c222a8049d204090a5ac Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 6 Apr 2023 16:20:22 +0200 Subject: [PATCH 20/34] Remove intro sentence that probably begs for a reference to a mission statement, but replace with a (perhaps) nice note --- docs/user/explanation/dedicated-platform.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index 4ac39ab097b..3877e35ed13 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -16,8 +16,6 @@ Choosing a dedicated documentation platform =========================================== This is an introduction to the most common benefits of choosing a dedicated platform for building and publishing documentation projects. -In other words, -we dive into some of the reasons behind Read the Docs' existence and vision. Let us start with a high-level overview: @@ -39,6 +37,13 @@ allows you to focus on other critical tasks, such as choosing documentation tools, structuring your documentation and having the perfect workflow. Not to mention *writing the documentation itself*! +.. note:: + + Read the Docs is the dedicated documentation platform that we are mostly hinting at, + but whenever possible, + we present the general case of a dedicated documentation platform since having *no* dedicated documentation platform at all is the present situation for many, + especially software projects. + If we observe a documentation project simply from the outside, we might only see the documentation as one or more deliverables, such as: A website, a PDF document, or an API documentation. From e7982bbedd8b4c25ed744af07472a4d9ffda8a63 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 11 Apr 2023 15:33:42 +0200 Subject: [PATCH 21/34] Improve language, added new section "batteries included", diagram about documentation life-cycle (draft) --- docs/user/explanation/dedicated-platform.rst | 73 ++++- docs/user/glossary.rst | 17 ++ docs/user/img/documentation-lifecycle.svg | 301 +++++++++++++++++++ 3 files changed, 382 insertions(+), 9 deletions(-) create mode 100644 docs/user/img/documentation-lifecycle.svg diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index 3877e35ed13..1d936d4b322 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -10,12 +10,11 @@ .. - A dedicated platform helps to solve tasks that you otherwise end up writing and maintaining your own scripts and CI tools for. .. - Always evolving: Read the Docs develops new features on-demand. So you get a dedicated platform that's maintained and has new features added. .. - Community: Related to the above, but perhaps worth mentioning that a lot of people are building tools and extensions that run on the platform etc. -.. - Batteries included / integrations: Flyout menu, search, SSL certificate Choosing a dedicated documentation platform =========================================== -This is an introduction to the most common benefits of choosing a dedicated platform for building and publishing documentation projects. +This is an introduction to the most common benefits of choosing a *dedicated* platform for building and publishing documentation projects. Let us start with a high-level overview: @@ -24,10 +23,18 @@ Let us start with a high-level overview: 🛠️ :ref:`documentation_tools` By choosing a tool-agnostic dedicated platform, - you can use the documentation tools that you want. + you can use documentation tools from open source eco-systems. 🚢️️ :ref:`workflows` - A dedicated CI/CD platform publishes your documentation automatically and versions it so you can focus on applying your own workflow and keep the documentation aligned with your product. + A dedicated documentation platform works like a :term:`CI/CD platform `, publishing and versioning your documentation automatically. + Most documentation projects need CI/CD automation, + and by choosing a dedicated platform, + you save building your own scripts and deployment workflows for documentation. + +🔋️ :ref:`batteries_included` + Read the Docs continues to develop new projects and ideas, + bringing additional powers to documentation projects that are hosted on the platform. + .. The following sections are about using a dedicated platform as a first-choice in order to free up space for other tasks. .. These paragraphs can benefit from being shortened and organized, but they are intended as the summary of the introduction. @@ -89,6 +96,15 @@ Read the Docs is a platform with over a decade of experience in automating docum The platform handles your current challenges or challenges that you face down the road. The right features are available when you need them. +.. figure:: /img/documentation-lifecycle.svg + :alt: A diagram of external effects to a documentation's life-cycle + + The number of effects on a life-cycle are many. + Some are caused by external factors, + changes to the product or project, + changes in the team, + vision etc. + Example: Automated versioning and redirects Once a documentation project is bootstrapped, the software product might change its version and remove or add features. @@ -131,15 +147,19 @@ your static website and additional :doc:`offline formats ` +* `MkDocs `__ and `Material for MkDocs `__ +* `Jupyter Book `__ +* `Pelican `__ +* `Docusaurus `__ +* `Docsy for Hugo `__ +* `Asciidoctor `__ * ...and any other tool that will install and run in a Docker container. -* ...and plugins/extensions for all of the above! +* ...and plugins/extensions/themes for all of the above. .. _workflows: @@ -184,6 +204,41 @@ Example: Automatic deploys with version tagging This is one of the core principles of the Diatáxis Methodology, which presents a universal structure and agile workflow methodology for documentation projects. + +.. _batteries_included: + +Batteries included +------------------ + +A common saying about a product that is ready to use in real life without a big effort is that the the product has *batteries included*. + +Several features of the Read the Docs platform are already mentioned in :ref:`lifecycle`. +But did you know that we also build and extend features directly for usage with your documentation tools? + +As a relatively new chapter in Read the Docs' history, +we are growing features that can be hard to maintain in the realm of a :term:`static website `. + +Example: Integrated :doc:`server side search ` + Many documentation tools include a small JavaScript-based search utilities. + Some don't. + In any case, + Read the Docs parses and indexes your HTML and offers a search form and search result dialogue that fits in any documentation project. + Search results can be delivered faster than JavaScript-based search tools and we also offer searches across multiple projects, + which is great for organizations. + +Example: :doc:`Flyout menu ` + By default, + an MkDocs and Sphinx project hosted on Read the Docs will have a little :term:`flyout menu` at the bottom of the screen. + The menu always contains the latest list of releases and alternative formats, + as well as convenient links to edit the project on |git_providers_or|. + + .. note:: + + As of April 2023, we are testing a new version of the :term:`flyout menu`, + which integrates with any documentation project. + Please contact :doc:`/support` for more information. + + .. Types of documentation projects .. ------------------------------- diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst index 0ae31f23737..4b39dbcd547 100644 --- a/docs/user/glossary.rst +++ b/docs/user/glossary.rst @@ -6,6 +6,11 @@ so that you have a reference for how we're using them. .. glossary:: + CI/CD + CI/CD is a common way to write *Continuous Integration and Continuous Deployment*. + In some scenarios, they exist as two separate platforms. + Read the Docs contains a combined CI/CD platform made for documentation. + dashboard The "admin" site where Read the Docs projects are managed and configured. This varies for our two properties: @@ -67,6 +72,18 @@ so that you have a reference for how we're using them. and hyphens. You can retrieve your project or version slugs from :doc:`our API `. + static website + Documentation projects served on Read the Docs are a type of *static websites*. + + A static site or static website is a collection of HTML files, images, CSS and JavaScript that do not change over time, + nor depend on which web server that is serving them. + + Tools to manage and generate static websites are commonly known as *static site generators* and there is a big overlap with documentation tools. + Some static site generators are also documentation tools, + and some documentation tools are also used to generate normal websites. + + For instance, :doc:`Sphinx ` is made for documentation but also used for blogging. + subproject Project A can be configured such that when requesting a URL ``/projects/``, the root of project B is returned. diff --git a/docs/user/img/documentation-lifecycle.svg b/docs/user/img/documentation-lifecycle.svg new file mode 100644 index 00000000000..ac435d04be6 --- /dev/null +++ b/docs/user/img/documentation-lifecycle.svg @@ -0,0 +1,301 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Product changesname + + + + + + + + + + + + + + + Maintainerscome and go + + + + + + + + + + + + + + + “Let’s refactorthe navigation!” + + + + + + + + + + + + + + + Big changes from 1.0 to 2.0=> new API, new theme + + + + + + + + + + + + + + + Features added anddeprecated in 1.1 + + + + + + Documentationlife-cycle + + + + + + + + + + + + + + + Contributor suggestsa new page orsmall change + + + + + + + + + + + + + + + Analyzing andunderstandingour users + + + + + + + + + + + + + + + Inviting stake-holders for a hidden release + + + + + + + + + + + + + + + Adding a new custom domain + + + + + + + + + + + + + + + New tool for APIdocumentation + + + + + + + + + + + + + + + Several active development branches + + + + + + + + From 705623d253388c8ee233df0df3ad242dcbdd86cc Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 11 Apr 2023 16:32:02 +0200 Subject: [PATCH 22/34] Add note about "Reader features" rename, update SVG --- docs/user/explanation/dedicated-platform.rst | 3 +- docs/user/img/documentation-lifecycle.svg | 47 +++++++++++++------- 2 files changed, 33 insertions(+), 17 deletions(-) diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index 1d936d4b322..81a43331092 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -10,6 +10,8 @@ .. - A dedicated platform helps to solve tasks that you otherwise end up writing and maintaining your own scripts and CI tools for. .. - Always evolving: Read the Docs develops new features on-demand. So you get a dedicated platform that's maintained and has new features added. .. - Community: Related to the above, but perhaps worth mentioning that a lot of people are building tools and extensions that run on the platform etc. +.. - Reader features: Alternative name for "Batteries included" is "Reader features" + Choosing a dedicated documentation platform =========================================== @@ -35,7 +37,6 @@ Let us start with a high-level overview: Read the Docs continues to develop new projects and ideas, bringing additional powers to documentation projects that are hosted on the platform. - .. The following sections are about using a dedicated platform as a first-choice in order to free up space for other tasks. .. These paragraphs can benefit from being shortened and organized, but they are intended as the summary of the introduction. diff --git a/docs/user/img/documentation-lifecycle.svg b/docs/user/img/documentation-lifecycle.svg index ac435d04be6..7dea16826bd 100644 --- a/docs/user/img/documentation-lifecycle.svg +++ b/docs/user/img/documentation-lifecycle.svg @@ -63,7 +63,7 @@ - + @@ -200,37 +200,37 @@ - Documentationlife-cycle + Documentationlifecycle - - - - - + + + + + - - Contributor suggestsa new page orsmall change + + Contributor suggestsa new page orsmall change - - - - - + + + + + - - Analyzing andunderstandingour users + + Analyzing andunderstandinguser behavior @@ -293,6 +293,21 @@ Several active development branches + + + + + + + + + + + + + Sudden success!100,000 page viewsper day. + + From d1be69bf91588ed26d2bdf26532e5a334db2d1d6 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 11 Apr 2023 16:33:14 +0200 Subject: [PATCH 23/34] Additional seealso:: for feature reference (TODO: include:: it) --- docs/user/explanation/dedicated-platform.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index 81a43331092..87f71dd05c1 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -239,6 +239,14 @@ Example: :doc:`Flyout menu ` which integrates with any documentation project. Please contact :doc:`/support` for more information. +.. TODO: Split this into an include:: since we are repeating it + +.. seealso:: + + :doc:`/reference/features` + A practical way to understand Read the Docs is to look at our :doc:`list of features `. + All these features ultimately sustain the life-cycle of a documentation project. + .. Types of documentation projects .. ------------------------------- From 2964fffd490f68c6e31e530fca8aeb54f77c3aff Mon Sep 17 00:00:00 2001 From: Benjamin Balder Bach Date: Tue, 11 Apr 2023 17:24:46 +0200 Subject: [PATCH 24/34] Apply suggestions from @humitos code review Co-authored-by: Manuel Kaufmann --- docs/user/explanation/advanced.rst | 2 +- docs/user/explanation/continuous-documentation.rst | 4 ++-- docs/user/index.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user/explanation/advanced.rst b/docs/user/explanation/advanced.rst index bc217f3be38..02eddc50e22 100644 --- a/docs/user/explanation/advanced.rst +++ b/docs/user/explanation/advanced.rst @@ -12,7 +12,7 @@ we explain some of the more specific or advanced concepts of writing documentati Learn more about multilingual documentation projects and how translation workflows are supported. ⏩️ :doc:`/downloadable-documentation` - An introduction to adding downloadable files to your documentation and keep them versioned. + An introduction to adding downloadable files that can be read offline to your documentation and keep them versioned. ⏩️ :doc:`/environment-variables` Environment variables can be used to make your documentation builds flexible and easy to customize. diff --git a/docs/user/explanation/continuous-documentation.rst b/docs/user/explanation/continuous-documentation.rst index 3b0c04aa17d..d63f5fc5f1a 100644 --- a/docs/user/explanation/continuous-documentation.rst +++ b/docs/user/explanation/continuous-documentation.rst @@ -15,8 +15,8 @@ Every time you change something in your documentation, Read the Docs will automa *build* your documentation, and finally *deploy* your documentation for readers to see. -The Continuous Integration and Continuous Deployment (CI/CD) features are configured with your repository provider, -such as GitHub, Bitbucket or GitLab. +The Continuous Integration and Continuous Deployment (:term:`CI/CD`) features are configured with your repository provider, +such as |git_providers_or|. With each change committed to your repository, we are notified by the configured :term:`webhook `. When a receive a *webhook* notification, we match it to a Read the Docs project. diff --git a/docs/user/index.rst b/docs/user/index.rst index 8bb2782e890..b1836096c24 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -121,7 +121,7 @@ Get a high-level overview of our platform: .. https://github.com/readthedocs/readthedocs.org/pull/10071 💡 :doc:`/explanation/dedicated-platform` - An introduction the reasons behind choosing a dedicated documentation platform such as Read the Docs. + An introduction to the reasons behind choosing a dedicated documentation platform such as Read the Docs. 💡 :doc:`/explanation/continuous-documentation` Discover the advantages of having your documentation continuously deployed. From 19c6422f0d2d50b19e8928b003673a55c4c05ce1 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 12 Apr 2023 11:30:45 +0200 Subject: [PATCH 25/34] A couple of quick updates from @humitos' review --- docs/user/explanation/dedicated-platform.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index 87f71dd05c1..bbd8e8fe455 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -1,8 +1,7 @@ .. This page seeks to put out lots of pointers to other articles in the documentation .. while giving an introduction that can be read consecutively. .. TODO: -.. - Links and references! -.. - Diagram in life-cycle section +.. - More links and references! .. .. There are other reasons that we could cover: .. - Code: If you write docs as code, you want this @@ -18,7 +17,10 @@ Choosing a dedicated documentation platform This is an introduction to the most common benefits of choosing a *dedicated* platform for building and publishing documentation projects. -Let us start with a high-level overview: +Simply put, +the role of a *dedicated documentation platform* is to offer a compelling set of features that documentation projects and their organizations or communities need. + +We start with a high-level overview: 🧭️️️ :ref:`lifecycle` A dedicated documentation platform has all the features to handle a variety of challenges and complexities that documentation projects meet during their lifecycle. @@ -65,9 +67,7 @@ A dedicated platform helps to solve tasks that you otherwise end up writing and `Comparison with GitHub Pages `__ On our website, we have a list of common tasks that developers and DevOps teams have to solve themselves on a generic CI. -Simply put, the role of a *dedicated documentation platform* is to offer a compelling set of features that documentation projects and their organizations or communities need. - -Read the Docs does exactly this in two versions: +Read the Docs has two separate platforms: |org_brand| and |com_brand|. :ref:`Read more about their differences `. .. Keeping this list commented out for now. From 53edc83d384e7907f22d642309faa7ad8e829d64 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 12 Apr 2023 11:37:12 +0200 Subject: [PATCH 26/34] Delete commented out feature list --- docs/user/explanation/dedicated-platform.rst | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index bbd8e8fe455..7e28a51f45e 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -70,24 +70,6 @@ A dedicated platform helps to solve tasks that you otherwise end up writing and Read the Docs has two separate platforms: |org_brand| and |com_brand|. :ref:`Read more about their differences `. -.. Keeping this list commented out for now. -.. The seealso about GitHub pages is better, since this is largely marketing content. -.. It's also nice to not break up the reading flow with a long list. Should delete... -.. * ✅️ Publishing a static website -.. * ✅️ Adding a fast cache layer for the website -.. * ✅️ Maintaining SSL -.. * ✅️ Notifications when things go wrong -.. * ✅️ Versioning -.. * ✅️ Letting users switch between versions -.. * ✅️ Offering additional formats (PDFs, ebooks) -.. * ✅️ Custom 404 pages -.. * ✅️ Building a fast search index -.. * ✅️ Having APIs to access documentation contents and integrate them elsewhere -.. * ✅️ Redirecting users that visit old URLs -.. * ✅️ Inviting a dedicated documentation team to manage all this -.. * ✅️ Manage access to private documentation projects -.. * ...this list is longer, and it is incidentally also the list of features that were built for Read the Docs. - .. _lifecycle: Features for the lifecycle of a documentation project From 109abd3e7894fd225fa74622351317d1e96dfddc Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 12 Apr 2023 11:41:44 +0200 Subject: [PATCH 27/34] Update definitions - define first, then examples --- docs/user/glossary.rst | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst index 4b39dbcd547..f346395df3c 100644 --- a/docs/user/glossary.rst +++ b/docs/user/glossary.rst @@ -45,6 +45,10 @@ so that you have a reference for how we're using them. Similar to :term:`Docs as Code`. webhooks + A webhook is a special URL that can be called from another service, + usually with a secret token. + It is commonly used to start a build or a deployment or to send a status update. + There are two important types of webhooks for Read the Docs: * Git providers have webhooks which are special URLs that Read the Docs can call in order to notify about documentation builds. @@ -73,10 +77,13 @@ so that you have a reference for how we're using them. :doc:`our API `. static website - Documentation projects served on Read the Docs are a type of *static websites*. + A static site or static website is a collection of HTML files, images, CSS and JavaScript that are served statically, + as opposed to dynamic websites that generate a unique response for each request, using databases and user sessions. + + Static websites are highly portable, as they do not depend on the webserver. + They can also be viewed offline. - A static site or static website is a collection of HTML files, images, CSS and JavaScript that do not change over time, - nor depend on which web server that is serving them. + Documentation projects served on Read the Docs are *static websites*. Tools to manage and generate static websites are commonly known as *static site generators* and there is a big overlap with documentation tools. Some static site generators are also documentation tools, From 38ad40f104b88701f2a3eb82050bff799a71eda3 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 12 Apr 2023 12:10:04 +0200 Subject: [PATCH 28/34] Add some more notes, ideas, polish introduction a bit --- docs/user/explanation/dedicated-platform.rst | 38 ++++++++++++-------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index 7e28a51f45e..1692aae9fa5 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -1,8 +1,9 @@ .. This page seeks to put out lots of pointers to other articles in the documentation .. while giving an introduction that can be read consecutively. .. TODO: -.. - More links and references! -.. +.. - More links and references! (remember the methodology section from a separate PR) +.. - Tiny screenshots possible? It would be nice if examples of features had little screenshots. + .. There are other reasons that we could cover: .. - Code: If you write docs as code, you want this .. - When you should NOT choose a dedicated documentation CI/CD: You just need a README in your Git repo! You need WYSIWYG so badly that you're probably better off with Confluence, GitBook or Google Docs. @@ -10,6 +11,14 @@ .. - Always evolving: Read the Docs develops new features on-demand. So you get a dedicated platform that's maintained and has new features added. .. - Community: Related to the above, but perhaps worth mentioning that a lot of people are building tools and extensions that run on the platform etc. .. - Reader features: Alternative name for "Batteries included" is "Reader features" +.. - Use-cases: The list would be really nice to wrap up with a set of use-cases. Software projects, onboarding docs, science, books etc. + +.. TODO: This article is kind of a "long-read" intended to read and share with other decision-makers. +.. It's not far from a "white paper", although it lacks case studies. +.. One way to help the reader would perhaps be to add a little box +.. Reading time: 15 minutes +.. Content: An elaborated case for why Read the Docs as a dedicated platform makes sense. +.. If you are interested in understanding why to use Read the Docs for the first time, this is a great starting point. Choosing a dedicated documentation platform @@ -19,8 +28,7 @@ This is an introduction to the most common benefits of choosing a *dedicated* pl Simply put, the role of a *dedicated documentation platform* is to offer a compelling set of features that documentation projects and their organizations or communities need. - -We start with a high-level overview: +This article gives a broad introduction to those features and their importance: 🧭️️️ :ref:`lifecycle` A dedicated documentation platform has all the features to handle a variety of challenges and complexities that documentation projects meet during their lifecycle. @@ -49,17 +57,11 @@ Not to mention *writing the documentation itself*! .. note:: - Read the Docs is the dedicated documentation platform that we are mostly hinting at, - but whenever possible, + Read the Docs is the *dedicated documentation platform* that we are mostly hinting at. + But whenever possible, we present the general case of a dedicated documentation platform since having *no* dedicated documentation platform at all is the present situation for many, especially software projects. -If we observe a documentation project simply from the outside, -we might only see the documentation as one or more deliverables, such as: -A website, a PDF document, or an API documentation. -But in order to get there, -a dedicated documentation platform is a reliable first choice. - A dedicated platform helps to solve tasks that you otherwise end up writing and maintaining your own scripts and CI tools for. .. seealso:: @@ -67,8 +69,16 @@ A dedicated platform helps to solve tasks that you otherwise end up writing and `Comparison with GitHub Pages `__ On our website, we have a list of common tasks that developers and DevOps teams have to solve themselves on a generic CI. -Read the Docs has two separate platforms: -|org_brand| and |com_brand|. :ref:`Read more about their differences `. +If we observe a documentation project simply from the outside, +we might only see the documentation as one or more deliverables, such as: +A website, a PDF document, or an API documentation. +But in order to get there, +a dedicated documentation platform is a reliable *first choice*. + +Finally, we should mention that Read the Docs offers two separate platforms: +|org_brand| and |com_brand|. +While they mostly share the same :ref:`open source platform `, +there are also :ref:`a couple of differences ` to be aware of. .. _lifecycle: From f5e0c09c0a5b1e7f28cdd8a1faf9f5ed047f258b Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Fri, 14 Apr 2023 08:38:18 -0700 Subject: [PATCH 29/34] Try and initial restructuring... There's still a bunch more work here, it's a bit overwhelming to try and get all the examples to fit together, and I'm running out of energy to do a whole refactor. --- docs/user/explanation/dedicated-platform.rst | 69 ++++++-------------- docs/user/index.rst | 9 +-- 2 files changed, 24 insertions(+), 54 deletions(-) diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index 1692aae9fa5..77f8f56d259 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -21,27 +21,26 @@ .. If you are interested in understanding why to use Read the Docs for the first time, this is a great starting point. -Choosing a dedicated documentation platform -=========================================== +Read the Docs: An all-in-one documentation solution +=================================================== -This is an introduction to the most common benefits of choosing a *dedicated* platform for building and publishing documentation projects. +This page covers the benefits of using an all-in-one documentation platform. +There are a number of approaches to writing and deploying documentation, +but using a platform built for this purpose provides you with a number of benefits that generic platforms do not. -Simply put, -the role of a *dedicated documentation platform* is to offer a compelling set of features that documentation projects and their organizations or communities need. +The role of a *dedicated documentation platform* is to offer a compelling set of features that documentation projects and their organizations need. This article gives a broad introduction to those features and their importance: 🧭️️️ :ref:`lifecycle` - A dedicated documentation platform has all the features to handle a variety of challenges and complexities that documentation projects meet during their lifecycle. + Documentation has a unique lifecycle, our platform handles a variety of challenges and complexities that documentation projects require, like versioning. 🛠️ :ref:`documentation_tools` - By choosing a tool-agnostic dedicated platform, - you can use documentation tools from open source eco-systems. + Support for a variety of documentation tools allows you the flexibility to choose the best tool for your project. 🚢️️ :ref:`workflows` - A dedicated documentation platform works like a :term:`CI/CD platform `, publishing and versioning your documentation automatically. - Most documentation projects need CI/CD automation, - and by choosing a dedicated platform, - you save building your own scripts and deployment workflows for documentation. + Our platform works like a :term:`CI/CD platform `, publishing and versioning your documentation automatically. + You save time not writing your own scripts and deployment workflows, + and get a reliable and reproducible process. 🔋️ :ref:`batteries_included` Read the Docs continues to develop new projects and ideas, @@ -50,35 +49,13 @@ This article gives a broad introduction to those features and their importance: .. The following sections are about using a dedicated platform as a first-choice in order to free up space for other tasks. .. These paragraphs can benefit from being shortened and organized, but they are intended as the summary of the introduction. -Using Read the Docs -allows you to focus on other critical tasks, -such as choosing documentation tools, structuring your documentation and having the perfect workflow. -Not to mention *writing the documentation itself*! - -.. note:: - - Read the Docs is the *dedicated documentation platform* that we are mostly hinting at. - But whenever possible, - we present the general case of a dedicated documentation platform since having *no* dedicated documentation platform at all is the present situation for many, - especially software projects. - -A dedicated platform helps to solve tasks that you otherwise end up writing and maintaining your own scripts and CI tools for. +Using Read the Docs allows you to focus on other critical tasks, +such as choosing structuring and writing your documentation itself! .. seealso:: `Comparison with GitHub Pages `__ - On our website, we have a list of common tasks that developers and DevOps teams have to solve themselves on a generic CI. - -If we observe a documentation project simply from the outside, -we might only see the documentation as one or more deliverables, such as: -A website, a PDF document, or an API documentation. -But in order to get there, -a dedicated documentation platform is a reliable *first choice*. - -Finally, we should mention that Read the Docs offers two separate platforms: -|org_brand| and |com_brand|. -While they mostly share the same :ref:`open source platform `, -there are also :ref:`a couple of differences ` to be aware of. + On our website, we have a list of common tasks that teams have to solve themselves on a generic CI. .. _lifecycle: @@ -156,8 +133,8 @@ Some examples include: .. _workflows: -Agile workflows with Continuous Integration and Deployment (CI/CD) ------------------------------------------------------------------- +Move faster by integrating the building and deployment of documentation +----------------------------------------------------------------------- Automating your `build and deploy process `, enables documentation writers to suggest changes, share previews, receive feedback and implement feedback quickly and iteratively. @@ -200,16 +177,12 @@ Example: Automatic deploys with version tagging .. _batteries_included: -Batteries included ------------------- - -A common saying about a product that is ready to use in real life without a big effort is that the the product has *batteries included*. - -Several features of the Read the Docs platform are already mentioned in :ref:`lifecycle`. -But did you know that we also build and extend features directly for usage with your documentation tools? +Better documentation reader experience +-------------------------------------- -As a relatively new chapter in Read the Docs' history, -we are growing features that can be hard to maintain in the realm of a :term:`static website `. +Read the Docs offers a number of features that are visible to readers of your documentation. +This gives you the ability to provide a nicer experience to your readers, +while also providing many benefits to the authors and maintainers. Example: Integrated :doc:`server side search ` Many documentation tools include a small JavaScript-based search utilities. diff --git a/docs/user/index.rst b/docs/user/index.rst index b1836096c24..b003557c446 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -121,16 +121,13 @@ Get a high-level overview of our platform: .. https://github.com/readthedocs/readthedocs.org/pull/10071 💡 :doc:`/explanation/dedicated-platform` - An introduction to the reasons behind choosing a dedicated documentation platform such as Read the Docs. + An introduction to the reasons behind choosing a dedicated documentation platform. 💡 :doc:`/explanation/continuous-documentation` Discover the advantages of having your documentation continuously deployed. -.. TODO: This next item needs its article to be finished in a separate PR -.. https://github.com/readthedocs/readthedocs.org/pull/10071 -.. TODO: 💡 Advanced topics: Deep-dive into Read the Docs -.. Get familiar with some of the more advanced topics of building and deploying documentation with Read the Docs. - +💡 :doc:`/explanation/advanced` + Get familiar with some of the more advanced topics of building and deploying documentation. How-to guides ------------- From 5a23748a292358d8db3dac9d53d23122ebea4184 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 18 Apr 2023 20:09:49 +0200 Subject: [PATCH 30/34] Add CDN, mention scaling from small project to enterprise, link to versioning and more --- docs/user/explanation/dedicated-platform.rst | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index 77f8f56d259..504d94fc2d3 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -66,6 +66,10 @@ Read the Docs is a platform with over a decade of experience in automating docum The platform handles your current challenges or challenges that you face down the road. The right features are available when you need them. +Some features respond to external factors, +while other features respond to the natural development of a documentation project. +The combined set of features make it possible to bootstrap a small documentation project and turn it into a mature enterprise product. + .. figure:: /img/documentation-lifecycle.svg :alt: A diagram of external effects to a documentation's life-cycle @@ -80,10 +84,12 @@ Example: Automated versioning and redirects the software product might change its version and remove or add features. Old versions of the product still need to be able to refer to their original documentation while new versions should not be unnecessarily complicated by documenting old features. - That is why Read the Docs supports versioning out-of-the-box and also gives you a mature set of options for creating :doc:`user-defined redirects `. - As your documentation grows and pages are moved around, versioning and redirects become critical. + :doc:`Versioning ` is a core part of documentation projects on our platform. + And on top of versioning support, + Read the Docs offers a mature set of :doc:`user-defined redirects `. + Example: Analytics Documentation websites benefit from knowing which pages are popular and how people discover them through online search. @@ -92,6 +98,16 @@ Example: Analytics And why should every documentation project have to implement their own analytics solution? For this, you can use :doc:`/reference/analytics`. +Example: Cloud hosting (CDN) + Read the Docs deploys and hosts your documentation. + Part of this package is to host documentation projects with a CDN in front of them, + so you never have to worry about incoming traffic. + + We also have intelligent caching, + so you don't have to worry about when to invalidate your cloud cache when your project is updated. + + Read more in :doc:`/reference/cdn`. + .. seealso:: :doc:`/reference/features` From ada4d4471089ac10a1a57bd4ce3677d0ac7631cb Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Tue, 18 Apr 2023 20:12:27 +0200 Subject: [PATCH 31/34] Lifecycle not life-cycle --- docs/user/explanation/dedicated-platform.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index 504d94fc2d3..4f7f284b38c 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -71,9 +71,9 @@ while other features respond to the natural development of a documentation proje The combined set of features make it possible to bootstrap a small documentation project and turn it into a mature enterprise product. .. figure:: /img/documentation-lifecycle.svg - :alt: A diagram of external effects to a documentation's life-cycle + :alt: A diagram of external effects to a documentation's lifecycle - The number of effects on a life-cycle are many. + The number of effects on a lifecycle are many. Some are caused by external factors, changes to the product or project, changes in the team, @@ -112,10 +112,8 @@ Example: Cloud hosting (CDN) :doc:`/reference/features` A practical way to understand Read the Docs is to look at our :doc:`list of features `. - All these features ultimately sustain the life-cycle of a documentation project. + All these features ultimately sustain the lifecycle of a documentation project. -.. insert life-cycle diagram. -.. new product + documentation project => new documentation pages => more product versions => more readers => more reader inputs => breaking changes => legacy product versions .. _documentation_tools: @@ -226,7 +224,7 @@ Example: :doc:`Flyout menu ` :doc:`/reference/features` A practical way to understand Read the Docs is to look at our :doc:`list of features `. - All these features ultimately sustain the life-cycle of a documentation project. + All these features ultimately sustain the lifecycle of a documentation project. .. Types of documentation projects From 8fc9b5127c4fb1b7403311d6e73d3c5eb52ea19e Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 20 Apr 2023 12:09:44 +0200 Subject: [PATCH 32/34] Update term ref --- docs/user/versions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/versions.rst b/docs/user/versions.rst index 46cb1984b5c..d5e3a8f19c8 100644 --- a/docs/user/versions.rst +++ b/docs/user/versions.rst @@ -12,7 +12,7 @@ we also create a ``stable`` version, tracking your most recent release. If you want a custom ``stable`` version, create either a tag or branch in your project with that name. -When you have :term:`webhook ` configured for your repository, +When you have :term:`webhook` configured for your repository, we will automatically build each version when you push a commit. How we envision versions working From 3de54d88c32f2fd96e493837c9904afd7ac0253f Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 21 Jun 2023 21:10:08 +0200 Subject: [PATCH 33/34] Update orphaned explanation index --- docs/user/explanation/index.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/user/explanation/index.rst b/docs/user/explanation/index.rst index b78ab9912aa..d18b2ab4051 100644 --- a/docs/user/explanation/index.rst +++ b/docs/user/explanation/index.rst @@ -6,12 +6,15 @@ Explanation =========== -⏩️ :doc:`/choosing-a-site` - Users often ask what the differences are between Read the Docs Community and Read the Docs for Business: here's an overview. +⏩️ :doc:`/explanation/dedicated-platform` + An introduction to what a dedicated documentation platform like Read the Docs does offers documentation projects. -⏩️ :doc:`/integrations` +⏩️ :doc:`/explanation/continuous-documentation` A high-level introduction to *Continuous Documentation Deployment*. +⏩️ :doc:`/config-file/index` + An explanation of the value of having a versioned configuration file for your project. + ⏩️ :doc:`/subprojects` Learn more about how several documentation projects can be combined and presented to the reader on the same website. @@ -29,9 +32,6 @@ Explanation :maxdepth: 1 :hidden: - /choosing-a-site - /integrations - /subprojects - /localization - /downloadable-documentation - /environment-variables + /explanation/dedicated-platform + /explanation/continuous-documentation + /explanation/advanced From 77cbb2c3749cd9b845f339111ef99ef69a5f0228 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 21 Jun 2023 21:16:04 +0200 Subject: [PATCH 34/34] Remove a couple of old comments --- docs/user/explanation/dedicated-platform.rst | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/user/explanation/dedicated-platform.rst b/docs/user/explanation/dedicated-platform.rst index 4f7f284b38c..45520602d6e 100644 --- a/docs/user/explanation/dedicated-platform.rst +++ b/docs/user/explanation/dedicated-platform.rst @@ -1,10 +1,9 @@ .. This page seeks to put out lots of pointers to other articles in the documentation .. while giving an introduction that can be read consecutively. .. TODO: -.. - More links and references! (remember the methodology section from a separate PR) .. - Tiny screenshots possible? It would be nice if examples of features had little screenshots. -.. There are other reasons that we could cover: +.. Inspiration for items to cover: .. - Code: If you write docs as code, you want this .. - When you should NOT choose a dedicated documentation CI/CD: You just need a README in your Git repo! You need WYSIWYG so badly that you're probably better off with Confluence, GitBook or Google Docs. .. - A dedicated platform helps to solve tasks that you otherwise end up writing and maintaining your own scripts and CI tools for. @@ -46,9 +45,6 @@ This article gives a broad introduction to those features and their importance: Read the Docs continues to develop new projects and ideas, bringing additional powers to documentation projects that are hosted on the platform. -.. The following sections are about using a dedicated platform as a first-choice in order to free up space for other tasks. -.. These paragraphs can benefit from being shortened and organized, but they are intended as the summary of the introduction. - Using Read the Docs allows you to focus on other critical tasks, such as choosing structuring and writing your documentation itself! @@ -133,8 +129,6 @@ A documentation tool simply needs to be able to run on Linux inside a Docker con Most documentation frameworks will do this. Some examples include: -.. TODO: expand the list and add links - * :doc:`Sphinx ` * `MkDocs `__ and `Material for MkDocs `__ * `Jupyter Book `__