Landing: day to day usage

Example of "How to use Read the Docs in your daily work" after reading the onboarding book on Book Club. The idea of this page is to show _exactly_ how customers will use Read the Docs on their day to day work to make them reach that "aha" moment when they realize this workflow is a lot easier than the one they are currently following. Goals: - explain how they will use Read the Docs daily - mention docs as code workflow - explain write, push, review and deploy stages - show images representing those exact stages - mention we don't provide an editor Page based on https://about.readthedocs.com/docs-as-code/ structure.
readthedocs · Jul 3, 2024 · b67eccd · b67eccd
1 parent 652947d
commit b67eccd
Show file tree

Hide file tree

Showing 6 changed files with 263 additions and 4 deletions.
diff --git a/content/images/usage/code-editor-light.png b/content/images/usage/code-editor-light.png
diff --git a/content/images/usage/code-editor.png b/content/images/usage/code-editor.png
diff --git a/content/images/usage/documentation.png b/content/images/usage/documentation.png
diff --git a/content/images/usage/pull-request-collaboration.png b/content/images/usage/pull-request-collaboration.png
diff --git a/content/includes/try-it-out.html b/content/includes/try-it-out.html
@@ -20,11 +20,11 @@ <h2 class="ui huge center aligned header">
             ```yaml
             version: 2
             build:
-              os: ubuntu-22.04
+              os: ubuntu-24.04
               tools:
-                python: "3.10"
+                python: "3.12"
                 # You can also specify other tool versions:
-                # nodejs: "16"
+                # nodejs: "20"
 
             # Build documentation in the docs/ directory with Sphinx
             sphinx:
@@ -96,4 +96,4 @@ <h2 class="ui huge center aligned header">
 
       </div>
     </div>
-</section>
+</section>
diff --git a/content/pages/usage.html b/content/pages/usage.html
@@ -0,0 +1,259 @@
+{#
+  The goal of this page is to explain in a simple way how users will use Read the Docs in their lives.
+#}
+<html>
+  <head>
+    <title>Using Read the Docs daily</title>
+    <meta name="template" content="page" />
+    <meta name="slug" content="usage" />
+    <meta name="status" content="hidden" />
+    <meta name="description" content="How to use Read the Docs in your daily basis to write, build and host your documentation." />
+  </head>
+  <body>
+
+{#
+  View this page at http://localhost:8080/usage/index.html
+#}
+
+{% import "partials/basic.html" as basic %}
+{% import "partials/features.html" as about %}
+{% import "partials/marketing.html" as marketing %}
+{% import "partials/technical.html" as technical %}
+{% import "partials/homepage.html" as homepage %}
+
+<section>
+  <div class="ui horizontally very padded container">
+    <div class="ui very padded centered grid">
+      <div class="middle aligned row">
+
+        <div class="ten wide computer sixteen wide tablet sixteen wide mobile column">
+          <div class="ui large left aligned basic vertical segment">
+            <h1 class="ui huge header">
+              Read the Docs in your daily work
+            </h1>
+
+            <p>
+              Read the Docs helps you with building, reviewing and publishing documentation for your customers.
+              Follow the <em>docs as code</em> pattern that you are already using.
+              Allow your readers to browse your documentation with shiny themes and perform searches accross all your projects.
+              They will really appreciate you are using Read the Docs for your documentation.
+            </p>
+
+            {# This should be a list of benefits, not features, since we have a feature listing in the side nav #}
+            <div class="ui list">
+              <div class="item"><i class="fad fa-check secondary icon"></i>Write documentation using a rich ecosystem of tools (MkDocs, Docusaurus, etc).</div>
+              <div class="item"><i class="fad fa-check secondary icon"></i>Version your documents with Git.</div>
+              <div class="item"><i class="fad fa-check secondary icon"></i>Preview each change before publishing.</div>
+              <div class="item"><i class="fad fa-check secondary icon"></i>Easily deploy docs on merge.</div>
+            </div>
+
+            <p>
+              Read the Docs is the <em>all-in-one</em> solution for docs as code.
+            </p>
+
+          </div>
+        </div>
+
+        <div class="six wide computer twelve wide tablet sixteen wide mobile column">
+          <div class="ui padded basic segment">
+            <div class="ui relaxed list">
+
+              {%- set header_1 = "Write the documentation" %}
+              {%- set slug_1 = "write" %}
+              {%- set icon_1 = "fa-pencil" -%}
+              <a href="#{{ slug_1 }}" class="ui small teal header item">
+                <i class="fad {{ icon_1 }} secondary big icon"></i>
+                <span class="content">
+                  {{ header_1 }}
+                  <span class="sub header">Write the documentation using your favourite editor.</span>
+                </span>
+              </a>
+
+              {%- set header_2 = "Push the changes to Git" %}
+              {%- set slug_2 = "git-integration" %}
+              {%- set icon_2 = "fa-code-commit" -%}
+              <a href="#{{ slug_2 }}" class="ui small header item">
+                <i class="fad {{ icon_2 }} secondary big icon"></i>
+                <span class="content">
+                  {{ header_2 }}
+                  <span class="sub header">Collaborate with your team by following the pull request and review workflow.</span>
+                </span>
+              </a>
+
+              {%- set header_3 = "Pull request previews" %}
+              {%- set slug_3 = "pull-request-previews" %}
+              {%- set icon_3 = "fa-file-plus-minus" -%}
+              <a href="#{{ slug_3 }}" class="ui small header item">
+                <i class="fad {{ icon_3 }} secondary big icon"></i>
+                <span class="content">
+                  {{ header_3 }}
+                  <span class="sub header">Verify changes to your documentation with a fully built documentation website for each pull request.</span>
+                </span>
+              </a>
+
+              {%- set header_4 = "One-click deployment" %}
+              {%- set slug_4 = "one-click-deployment" %}
+              {%- set icon_4 = "fa-rocket" -%}
+              <a href="#{{ slug_4 }}" class="ui small header item">
+                <i class="fad {{ icon_4 }} secondary big icon"></i>
+                <span class="content">
+                  {{ header_4 }}
+                  <span class="sub header">Automatically deploy your docs each time you <em>merge to main</em>.</span>
+                </span>
+              </a>
+
+            </div>
+          </div>
+        </div>
+
+      </div>
+    </div>
+  </div>
+
+</section>
+
+{% macro about_divide(text=None) %}
+  <div class="ui text container">
+    <div class="ui {%- if text %} horizontal {%- endif %} divider">
+      {% if text %}{{ text }}{% endif %}
+    </div>
+  </div>
+{% endmacro %}
+
+{{ about_divide() }}
+
+<section>
+  <div class="ui very padded container">
+    <div class="ui vertically padded centered grid" id="{{ slug_1 }}">
+
+      {% call about.step(
+          header=header_1,
+          image="/images/usage/code-editor-light.png",
+          image_alt="Visual Studio Code editor",
+          icon=icon_1) %}
+        {% markdown %}
+        Write documentation using your favourite editor.
+        Read the Docs doesn't force you to use any particular, WebUI, or WYSIWYG editor.
+        You can use the one you already love.
+        {% endmarkdown %}
+      {% endcall %}
+
+    </div>
+  </div>
+
+  {{ about_divide() }}
+
+  <div class="ui very padded container" id="{{ slug_2 }}">
+    <div class="ui vertically padded centered grid">
+
+      {% call about.step(
+          header=header_2,
+          image="/images/usage/pull-request-collaboration.png",
+          image_alt="Opened pull request on GitHub",
+          icon=icon_2) %}
+        {% markdown %}
+        Once you are done writing the documentation, push you changes to Git and open a pull request to collaborate with your team.
+        Accept or reject suggestions from your co-workers while previewing the live changes on Read the Docs.
+        {% endmarkdown %}
+
+        <a class="ui basic primary button" href="https://docs.readthedocs.io/page/reference/git-integration.html">
+          <i class="fad fa-book icon" aria-hidden="true"></i>
+          Documentation
+        </a>
+
+      {% endcall %}
+
+    </div>
+  </div>
+
+  {{ about_divide() }}
+
+  <div class="ui very padded container" id="{{ slug_3 }}">
+    <div class="ui vertically padded centered grid">
+
+      {% call about.step(
+          header=header_3,
+          image="/images/docs-as-code/visual-diff.png",
+          image_alt="Visual diff between two versions",
+          icon=icon_3) %}
+        {% markdown %}
+        When the pull request opened, you and your team can see the live changes on Read the Docs to evaluate the look & feel,
+        but also to find style issues that are impossible to find out from the diff code in the pull request.
+        {% endmarkdown %}
+
+        <a class="ui basic primary button" href="https://docs.readthedocs.io/page/pull-requests.html">
+          <i class="fad fa-book icon" aria-hidden="true"></i>
+          Documentation
+        </a>
+
+      {% endcall %}
+
+    </div>
+  </div>
+
+  {{ about_divide() }}
+
+  <div class="ui very padded container" id="{{ slug_4 }}">
+    <div class="ui vertically padded centered grid">
+
+      {% call about.step(
+          header=header_4,
+          image="/images/usage/documentation.png",
+          image_alt="Documentation built on Read the Docs",
+          icon=icon_4) %}
+      {% markdown %}
+      After getting an approval in your pull request and you merged it,
+      Read the Docs will build and deploy those changes in production automatically.
+      {% endmarkdown %}
+
+        {# TODO: Have a better docs page for deployment #}
+        <a class="ui basic primary button" href="https://docs.readthedocs.io/page/builds.html">
+          <i class="fad fa-book icon" aria-hidden="true"></i>
+          Documentation
+        </a>
+
+      {% endcall %}
+
+    </div>
+  </div>
+
+</section>
+
+
+{# Try it out code block #}
+{% include "includes/try-it-out.html" %}
+
+{% block bottom_callout %}
+  <section>
+    <div class="ui very padded container">
+      <div class="ui grid center aligned">
+        <div class="row">
+          <div class="column twelve wide computer sixteen wide tablet">
+            <div class="ui basic vertical huge segment">
+              <h2 class="ui center aligned header">
+                Save time and headaches!
+              </h2>
+
+              <p>
+                Simplify you day to day work by writing, building, previewing and publishing your documentation with Read the Docs.
+                Collaborate with all your team in an easy way that everybody understands and can immediately see the changes after pushing them to Git.
+              </p>
+
+              <p>
+                <a class="ui large teal stackable button"
+                data-analytics="signup-modal"
+                 onclick="jQuery('#signup-modal').modal('show');">
+                  <i class="fad fa-rocket icon"></i>
+                  Sign up now
+                </a>
+              </p>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </section>
+  {% endblock bottom_callout %}
+
+  </body>
+</html>