docs: added diataxis sections and landing pages

* Added direct link to web-based Libera chat for convenience * Added text to point out "Have a question" link at top of pages * added overview/landing pages for each Diataxis section * added cards to docs home page for Diataxis sections
canonical · Nov 22, 2022 · e697459 · e697459
1 parent b0f3a3d
commit e697459
Show file tree

Hide file tree

Showing 7 changed files with 105 additions and 4 deletions.
diff --git a/docs-requirements.txt b/docs-requirements.txt
@@ -4,3 +4,4 @@ myst-parser
 sphinx==5.1.1
 sphinx_autobuild
 sphinx_copybutton
+sphinx_design
diff --git a/docs/conf.py b/docs/conf.py
@@ -29,6 +29,7 @@
 extensions = [
     "myst_parser",
     "sphinx_copybutton",
+    "sphinx_design",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/explanations.rst b/docs/explanations.rst
@@ -0,0 +1,15 @@
+Ubuntu Pro Client explanations
+==============================
+
+Our explanatory and conceptual guides are written to provide a better understanding of how the Ubuntu Pro Client (``pro``) works. They enable you to expand your knowledge and become better at using and configuring ``pro``.
+
+Explanations
+------------
+
+..  toctree::
+    :maxdepth: 1
+    :glob:
+
+    explanations/*
+
+-----
diff --git a/docs/howtoguides.rst b/docs/howtoguides.rst
@@ -0,0 +1,18 @@
+Ubuntu Pro Client how-to guides
+===============================
+
+If you have a specific goal and are already familiar with the Ubuntu Pro Client (``pro``), our How-to guides have more in-depth detail than our tutorials and can be applied to a wider range of situations.
+
+They will help you to achieve a particular end result, but may require you to understand and adapt the steps to fit your specific requirements.
+
+How-to guides
+-------------
+
+..  toctree::
+    :maxdepth: 1
+    :glob:
+
+    howtoguides/*
+
+-----
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -18,13 +18,44 @@ If you need any of those services for your machine, ``pro`` is the right tool fo
 
 ``pro`` is already installed on every Ubuntu system. Try it out by running ``pro help``!
 
+-----
+
+.. grid:: 1 1 2 2
+   :gutter: 3
+
+   .. grid-item-card:: **Tutorials**
+       :link: tutorials
+       :link-type: doc
+
+       Get started - a hands-on introduction to Ubuntu Pro Client for new users
+
+   .. grid-item-card:: **How-to guides**
+       :link: howtoguides
+       :link-type: doc
+
+       Step-by-step guides covering key operations and common tasks
+
+   .. grid-item-card:: **Explanations**
+       :link: explanations
+       :link-type: doc
+
+       Discussion and clarification of key topics
+
+   .. grid-item-card:: **References**
+       :link: references
+       :link-type: doc
+
+       Technical information - specifications, APIs, architecture
+
+-----
+
 Getting help
 ************
 
-Having trouble? We would like to help!
+Having trouble? We would like to help! For help on a specific page in this documentation, click on the "Have a question?" link at the top of that page. You can also...
 
-- Ask a question in the ``#ubuntu-server`` IRC channel on Libera
-- Find a bug? `Report bugs on Launchpad`_
+- Ask a question in the ``#ubuntu-server`` `IRC channel on Libera`_
+- `Report bugs on Launchpad`_
 
 Project and community
 *********************
@@ -46,7 +77,7 @@ community projects, contributions, suggestions, fixes and constructive feedback.
 .. toctree::
    :hidden:
    :titlesonly:
-   :caption: How to guides
+   :caption: How-to guides
    :glob:
 
    howtoguides/*
@@ -78,3 +109,4 @@ community projects, contributions, suggestions, fixes and constructive feedback.
 .. _Report bugs on Launchpad: https://bugs.launchpad.net/ubuntu-advantage-tools/+filebug
 .. _Code of conduct: https://ubuntu.com/community/code-of-conduct
 .. _Contribute: https://github.com/canonical/ubuntu-advantage-client/blob/main/CONTRIBUTING.md
+.. _IRC channel on Libera: https://kiwiirc.com/nextclient/irc.libera.chat/ubuntu-server
diff --git a/docs/references.rst b/docs/references.rst
@@ -0,0 +1,15 @@
+Ubuntu Pro Client references
+============================
+
+Our Reference section contains support information for the Ubuntu Pro Client. This includes details on the network requirements, API definitions, support matrices and so on.
+
+References
+----------
+
+..  toctree::
+    :maxdepth: 1
+    :glob:
+
+    references/*
+
+-----
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
@@ -0,0 +1,19 @@
+Ubuntu Pro Client tutorials
+===========================
+
+This section of our documentation contains step-by-step tutorials to help outline what the Ubuntu Pro Client (``pro``) is capable of, while helping you to achieve specific aims.
+
+We hope our tutorials make as few assumptions as possible and are accessible to anyone with an interest in ``pro``. They should be a great place to start learning about ``pro``, how it works, and what it's capable of.
+
+-----
+
+Tutorials
+---------
+
+..  toctree::
+    :maxdepth: 1
+    :glob:
+
+    tutorials/*
+
+-----