Skip to content

Commit f3397d5

Browse files
ericholscherhumitos
ericholscher
and
humitos
authored
Move Docs as Code -> Addons, and update Docs as Code (#279)
* Move Docs as Code -> Addons, and update Docs as Code This is the start of a reader features / addons page, and a small update to the docs as code page. TODO: * Update images on Docs as Code page * Work on copy * Update Docs as code page * Add links to docs * Add CTA * Rename addons -> reader features * Small copy edits * Update top nav * Last copy updates * More benefits * Use slug var * Apply suggestions from code review Co-authored-by: Manuel Kaufmann <[email protected]> * Update flyout image * Shrink file * Once more * Update docs links * Add docs links to reader page * Shorter title * Shorter still * Move image * Link Docs as code page from authoring --------- Co-authored-by: Manuel Kaufmann <[email protected]>
1 parent 2456537 commit f3397d5

File tree

12 files changed

+331
-88
lines changed

12 files changed

+331
-88
lines changed

‎content/images/docs-as-code/deploy.png

33.5 KB
Loading

‎content/images/docs-as-code/flyout-zoomed.png

26.6 KB
Loading

‎content/images/docs-as-code/gh-integration.png

43.3 KB
Loading

‎content/images/docs-as-code/analytics.png renamed to ‎content/images/features/analytics.png

File renamed without changes.

‎content/images/docs-as-code/flyout.png renamed to ‎content/images/features/flyout.png

File renamed without changes.

‎content/images/docs-as-code/notification.png renamed to ‎content/images/features/notification.png

File renamed without changes.

‎content/images/features/offline-formats-django.png

31.7 KB
Loading

‎content/images/docs-as-code/search.png renamed to ‎content/images/features/search.png

File renamed without changes.

‎content/pages/docs-as-code.html

+80-85
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1+
12
{#
23
The goal of this page is to sell Read the Docs to users already using the docs-as-code pattern.
34
Highlighting that without doing anything extra, they get lot of features for free.
45
#}
56
<html>
67
<head>
7-
<title>Docs as code made easy</title>
8+
<title>Docs as code hosting with standard tools</title>
89
<meta name="template" content="page" />
910
<meta name="slug" content="docs-as-code" />
1011
<meta name="status" content="hidden" />
@@ -30,25 +31,25 @@
3031
<div class="ten wide computer sixteen wide tablet sixteen wide mobile column">
3132
<div class="ui large left aligned basic vertical segment">
3233
<h1 class="ui huge header">
33-
<em>Docs as code</em> has never been that easy
34+
Take the confusion out of <em>docs as code</em>
3435
</h1>
3536

3637
<p>
37-
Treat your documentation in the same way as you treat your code by following the
38-
<a href="https://docs-as-co.de/" target="_blank" rel="nofollow">docs as code pattern</a>:
38+
Read the Docs is the go-to solution for open source and business for <em>docs as code</em> hosting.
39+
Use our standard process to build, publish, and host your documentation.
40+
Giving you all the features you care about <strong>without having to reinvent the wheel</strong>.
3941
</p>
4042

43+
{# This should be a list of benefits, not features, since we have a feature listing in the side nav #}
4144
<div class="ui list">
4245
<div class="item"><i class="fad fa-check secondary icon"></i>Write documentation using a rich ecosystem of tools (MkDocs, Docusaurus, etc).</div>
4346
<div class="item"><i class="fad fa-check secondary icon"></i>Version your documents with Git.</div>
44-
<div class="item"><i class="fad fa-check secondary icon"></i>Test your documentation builds correctly.</div>
45-
<div class="item"><i class="fad fa-check secondary icon"></i>Preview the changes before publishing.</div>
46-
<div class="item"><i class="fad fa-check secondary icon"></i>Automate the publication process.</div>
47+
<div class="item"><i class="fad fa-check secondary icon"></i>Preview each change before publishing.</div>
48+
<div class="item"><i class="fad fa-check secondary icon"></i>Easily deploy docs on merge</div>
4749
</div>
4850

4951
<p>
50-
Read the Docs is the <em>"all in one"</em> solution that helps you to make this process easy providing
51-
integrated features with zero effort.
52+
Read the Docs is the <em>all-in-one</em> solution for docs as code.
5253
</p>
5354

5455
</div>
@@ -58,55 +59,50 @@ <h1 class="ui huge header">
5859
<div class="ui padded basic segment">
5960
<div class="ui relaxed list">
6061

61-
{%- set header_1 = "Traffic and search analytics" %}
62-
{%- set icon_1 = "fa-chart-mixed" -%}
63-
<a href="#analytics" class="ui small teal header item">
62+
{%- set header_1 = "Versioning" %}
63+
{%- set slug_1 = "versioning" %}
64+
{%- set icon_1 = "fa-layer-group" -%}
65+
<a href="#{{ slug_1 }}" class="ui small teal header item">
6466
<i class="fad {{ icon_1 }} secondary big icon"></i>
6567
<span class="content">
6668
{{ header_1 }}
67-
<span class="sub header">Know more about how your readers use your documentation.</span>
69+
<span class="sub header">Give your users documentation for their exact version of your product.</span>
6870
</span>
6971
</a>
7072

71-
{%- set header_2 = "Notifications" %}
72-
{%- set icon_2 = "fa-messages" -%}
73-
<a href="#notifications" class="ui small header item">
73+
{%- set header_2 = "Git integration" %}
74+
{%- set slug_2 = "git-integration" %}
75+
{%- set icon_2 = "fa-code-commit" -%}
76+
<a href="#{{ slug_2 }}" class="ui small header item">
7477
<i class="fad {{ icon_2 }} secondary big icon"></i>
7578
<span class="content">
7679
{{ header_2 }}
77-
<span class="sub header">Warn readers about reading and old version of the documentation.</span>
80+
<span class="sub header">Use Git for development and documentation, making collaboration easy.</span>
7881
</span>
7982
</a>
8083

81-
{%- set header_3 = "Search as you type" %}
82-
{%- set icon_3 = "fa-magnifying-glass" -%}
83-
<a href="#search" class="ui small header item">
84+
{%- set header_3 = "Pull request previews" %}
85+
{%- set slug_3 = "pull-request-previews" %}
86+
{%- set icon_3 = "fa-file-plus-minus" -%}
87+
<a href="#{{ slug_3 }}" class="ui small header item">
8488
<i class="fad {{ icon_3 }} secondary big icon"></i>
8589
<span class="content">
8690
{{ header_3 }}
87-
<span class="sub header">Quickly find exactly what you are looking for.</span>
91+
<span class="sub header">Verify changes to your documentation with a fully built documentation website for each pull request.</span>
8892
</span>
8993
</a>
9094

91-
{%- set header_4 = "Visual diff on pull requests" %}
92-
{%- set icon_4 = "fa-file-plus-minus" -%}
93-
<a href="#visual-diff" class="ui small header item">
95+
{%- set header_4 = "One-click deployment" %}
96+
{%- set slug_4 = "One-click-deployment" %}
97+
{%- set icon_4 = "fa-gears" -%}
98+
<a href="#{{ slug_4 }}" class="ui small header item">
9499
<i class="fad {{ icon_4 }} secondary big icon"></i>
95100
<span class="content">
96101
{{ header_4 }}
97-
<span class="sub header">Review PR changes visually.</span>
102+
<span class="sub header">Automatically deploy your docs each time you <em>merge to main</em>.</span>
98103
</span>
99104
</a>
100105

101-
{%- set header_5 = "Read the Docs flyout" %}
102-
{%- set icon_5 = "fa-bars" -%}
103-
<a href="#flyout" class="ui small header item">
104-
<i class="fad {{ icon_5 }} secondary big icon"></i>
105-
<span class="content">
106-
{{ header_5 }}
107-
<span class="sub header">Select between multiple versions and translations.</span>
108-
</span>
109-
</a>
110106
</div>
111107
</div>
112108
</div>
@@ -129,129 +125,128 @@ <h1 class="ui huge header">
129125

130126
<section>
131127
<div class="ui very padded container">
132-
<div class="ui vertically padded centered grid" id="analytics">
128+
<div class="ui vertically padded centered grid" id="{{ slug_1 }}">
133129

134130
{% call about.step(
135131
header=header_1,
136-
image="/images/docs-as-code/analytics.png",
137-
image_alt="Graph showing traffic and search analytics in a period",
132+
image="/images/docs-as-code/flyout-zoomed.png",
133+
image_alt="Flyout showing versions of a documentation project",
138134
icon=icon_1) %}
139135
{% markdown %}
140-
Explore traffic analytics and understand what are the pages your readers read the most.
141-
**Prioritize the work** to improve them before other pages with less traffic.
142-
Find out what are the terms your users search the most and write documentation pages
143-
that include those terms so they can easily find them.
136+
Read the Docs can host multiple versions of your docs.
137+
Keep your 1.0 and 2.0 documentation online,
138+
so your users can always find the right version.
144139
{% endmarkdown %}
140+
<a class="ui basic primary button" href="https://docs.readthedocs.io/page/versions.html">
141+
<i class="fad fa-book icon" aria-hidden="true"></i>
142+
Documentation
143+
</a>
145144
{% endcall %}
146145

147146
</div>
148147
</div>
149148

150149
{{ about_divide() }}
151150

152-
<div class="ui very padded container" id="notification">
151+
<div class="ui very padded container" id="{{ slug_2 }}">
153152
<div class="ui vertically padded centered grid">
154153

155154
{% call about.step(
156155
header=header_2,
157-
image="/images/docs-as-code/notification.png",
158-
image_alt="Notification on a old version",
156+
image="/images/docs-as-code/gh-integration.png",
157+
image_alt="Read the Docs checks on GitHub",
159158
icon=icon_2) %}
160159
{% markdown %}
161-
Clearly communicate readers they are reading an outdated version of the documentation,
162-
and **reduce support requests** from old version of your product.
160+
Integrating directly with GitHub allows developers and documentation authors to collaborate seemlessly.
161+
You can author your documentation in any text editor,
162+
and using whatever format is most comfortable for you.
163163
{% endmarkdown %}
164+
165+
<a class="ui basic primary button" href="https://docs.readthedocs.io/page/reference/git-integration.html">
166+
<i class="fad fa-book icon" aria-hidden="true"></i>
167+
Documentation
168+
</a>
169+
164170
{% endcall %}
165171

166172
</div>
167173
</div>
168174

169175
{{ about_divide() }}
170176

171-
<div class="ui very padded container" id="search">
177+
<div class="ui very padded container" id="{{ slug_3 }}">
172178
<div class="ui vertically padded centered grid">
173179

174180
{% call about.step(
175181
header=header_3,
176-
image="/images/docs-as-code/search.png",
177-
image_alt="Read the Docs pull request review checks in a GitHub pull request",
182+
image="/images/docs-as-code/visual-diff.png",
183+
image_alt="Visual diff between two versions",
178184
icon=icon_3) %}
179185
{% markdown %}
180-
Always find what you are looking for at the tip of your fingers with our powerful ElasticSearch engine.
181-
Search on a **single or accross multiple projects** at once.
186+
Once you have your documentation in Git, you can preview changes before merging them.
187+
Every time you push a commit to a pull request,
188+
Read the Docs will build your documentation and show you the changes.
182189
{% endmarkdown %}
190+
191+
<a class="ui basic primary button" href="https://docs.readthedocs.io/page/pull-requests.html">
192+
<i class="fad fa-book icon" aria-hidden="true"></i>
193+
Documentation
194+
</a>
195+
183196
{% endcall %}
184197

185198
</div>
186199
</div>
187200

188201
{{ about_divide() }}
189202

190-
<div class="ui very padded container" id="visual-diff">
203+
<div class="ui very padded container" id="{{ slug_4 }}">
191204
<div class="ui vertically padded centered grid">
192205

193206
{% call about.step(
194207
header=header_4,
195-
image="/images/docs-as-code/visual-diff.png",
196-
image_alt="Visual diff between two versions",
208+
image="/images/docs-as-code/deploy.png",
209+
image_alt="Page showing build success",
197210
icon=icon_4) %}
198211
{% markdown %}
199-
Visuallize documentation changes *"in situ"* from pull requests before merging them.
200-
**Understand what exacly changed** in a simple and visual way.
212+
Once you're reviewed your changes, you can deploy the exact same way you do with your code.
213+
When you merge to main, Read the Docs will automatically update your docs in production.
201214
{% endmarkdown %}
202-
{% endcall %}
203-
204-
</div>
205-
</div>
206-
207-
{{ about_divide() }}
208215

209-
<div class="ui very padded container" id="flyout">
210-
<div class="ui vertically padded centered grid">
216+
{# TODO: Have a better docs page for deployment #}
217+
<a class="ui basic primary button" href="https://docs.readthedocs.io/page/builds.html">
218+
<i class="fad fa-book icon" aria-hidden="true"></i>
219+
Documentation
220+
</a>
211221

212-
{% call about.step(
213-
header=header_5,
214-
image="/images/docs-as-code/flyout.png",
215-
image_alt="Read the Docs flyout",
216-
icon=icon_5) %}
217-
{% markdown %}
218-
Let your users select between **multiple versions and translations** of your documentation in a quick way using the flyout menu.
219-
{% endmarkdown %}
220222
{% endcall %}
221223

222224
</div>
223225
</div>
226+
224227
</section>
225228

226229

227230
{# Try it out code block #}
228-
{% include "includes/try-it-out-docusaurus.html" %}
231+
{% include "includes/try-it-out.html" %}
229232

230-
{% block homepage_bottom_callout %}
233+
{% block bottom_callout %}
231234
<section>
232235
<div class="ui very padded container">
233236
<div class="ui grid center aligned">
234237
<div class="row">
235238
<div class="column twelve wide computer sixteen wide tablet">
236239
<div class="ui basic vertical huge segment">
237240
<h2 class="ui center aligned header">
238-
Still not convinced? Try it yourself <i class="fad fa-rocket icon"></i>
241+
Automate your docs with Read the Docs
239242
</h2>
240243

241-
{% markdown %}
242-
Import your existing project or create one following our [tutorial](https://docs.readthedocs.io/en/stable/tutorial/),
243-
and try it yourself.
244-
All these features will be enabled by default when using the
245-
[``build.commands``](https://docs.readthedocs.io/en/latest/config-file/v2.html#build-commands)
246-
config key as shown in the example.
247-
{% endmarkdown %}
248-
249244
<p>
250245
<a class="ui large teal stackable button"
251246
data-analytics="signup-modal"
252247
onclick="jQuery('#signup-modal').modal('show');">
253248
<i class="fad fa-rocket icon"></i>
254-
Get started for free
249+
Sign up
255250
</a>
256251
</p>
257252
</div>
@@ -260,7 +255,7 @@ <h2 class="ui center aligned header">
260255
</div>
261256
</div>
262257
</section>
263-
{% endblock homepage_bottom_callout %}
258+
{% endblock bottom_callout %}
264259

265260
</body>
266261
</html>

0 commit comments

Comments
 (0)