Updated structure, content, styling

nlk-jan · Apr 4, 2022 · e4cecce · e4cecce
1 parent 45896dd
commit e4cecce
Show file tree

Hide file tree

Showing 12 changed files with 430 additions and 89 deletions.
diff --git a/_static/diataxis.css b/_static/diataxis.css
@@ -7,7 +7,8 @@ h1 {
 }
 
 h2 {
-  font-size: 24px;
+  font-weight: 600;
+  font-size: 32px;
   line-height: 32px;
 }
 
@@ -89,6 +90,53 @@ div.sidebar-contact a:hover {color: #FF9300;}
 div.sidebar-tree .toctree-l1>.reference {color: gray;}
 div.sidebar-tree .toctree-l1>.reference:hover {color: #FF9300;}
 
+input.sidebar-search {
+    border: none;
+/*    border-top: 1px solid #FF9300;
+    border-bottom: none;
+    padding-top: 1em;
+    margin-top: 1em;
+*/}
+
+div.sidebar-tree ul {
+    border-bottom: 1px solid #FF9300;
+    padding: 1em 0;
+}
+
 .toctree-checkbox~label .icon svg {color: #FF9300;}
 
 .toc-tree li.scroll-current>.reference {color: #FF9300;}
+
+table.docutils {
+  border: 1px solid #FF9300;
+}
+
+table.docutils thead td {
+    border-bottom: 2px solid #FF9300;
+    border-right: 1px solid #FF9300;
+}
+
+table.docutils th.head {
+    padding: .5rem 0;
+}
+
+table.docutils th.stub {
+    text-align: right;
+
+}
+
+table.docutils td, table.docutils th {
+    border-right: 1px solid #FF9300;
+}
+
+table.docutils tr:last-child td,
+table.docutils tr:last-child th {
+    border-bottom: 1px solid #FF9300;
+}
+
+div.lined div.sd-col:nth-child(2n) {border-bottom: 1px solid #FF9300;}
+
+@media only screen and (min-width: 576px) {
+  div.lined div.sd-col {border-bottom: 1px solid #FF9300;}
+}
+
diff --git a/adoption.rst b/adoption.rst
@@ -9,10 +9,23 @@
 Who's using Diátaxis?
 =============================================
 
+..  rst-class:: quote
+
+    At Gatsby we recently reorganized our open-source documentation, and the Diátaxis framework was our go-to resource
+    throughout the project. The four quadrants helped us prioritize the user’s goal for each type of documentation. By
+    restructuring our documentation around the Diátaxis framework, we made it easier for users to discover the
+    resources that they need when they need them.
+
+..  rst-class:: attribution
+
+  \- Megan Sullivan (`@meganesulli <https://twitter.com/meganesulli>`_)
+
+
 ..  sidebar:: Not listed here?
 
-    If you're using the system, or are in the process of adopting it, please let us know if you'd like to be
-    listed here.
+    If you're using the system, or are in the process of adopting it, please let me know if you'd
+    like to be listed here. The best way is to `submit a pull request via GitHub
+    <https://github.com/evildmp/diataxis-documentation-framework/>`_.
 
 This is an incomplete list of projects, products and organisations that have adopted the system in their own
 bodies of documentation. In some cases the adoption remains partial or is still a work in progress.

diff --git a/conf.py b/conf.py
@@ -27,8 +27,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-]
+extensions = ["sphinx_design"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -63,9 +62,8 @@
 html_sidebars = {"**": [
 "sidebar/scroll-start.html",
 "sidebar/brand.html",
-"sidebar/search.html",
 "sidebar/navigation.html",
-"sidebar/contact.html",
+"sidebar/search.html",
 "sidebar/ethical-ads.html",
 "sidebar/scroll-end.html",
 ]}

diff --git a/contact.rst b/contact.rst
@@ -0,0 +1,17 @@
+.. _contact:
+
+Contact the author
+===================
+
+`Email Daniele Procida <[email protected]>`_. I read everything I receive. I appreciate all the
+interest and do my best to reply, but I get a considerable quantity of email related to Diátaxis
+and I can't promise to respond to every message.
+
+If you'd like to discuss Diátaxis with other users, please see the *#diataxis* channel on the
+`Write the Docs Slack group <https://www.writethedocs.org/slack/>`_, or the `Discussions
+<https://github.com/evildmp/diataxis-documentation-framework/discussions>`_ section of the `GitHub
+repository <https://github.com/evildmp/diataxis-documentation-framework>`_.
+
+You can also submit a pull request to have your documentation listed in the :ref:`Who's using
+Diátaxis <adoption>` or to suggest an improvement, or `file an issue
+<https://github.com/evildmp/diataxis-documentation-framework/issues>`_.
diff --git a/development.rst b/development.rst
diff --git a/how-to-guides.rst b/how-to-guides.rst
@@ -30,35 +30,14 @@ sections of your documentation.
 
 ===========
 
-How-to guides vs tutorials
+Tutorials vs how-to guides
 ----------------------------
 
 **How-to guides are wholly distinct from tutorials**. They are easily conflated, as both describe a series of practical
 steps that lead to the completion of some task. The user-needs that they serve are quite different however, and
 conflating them is at the root of many difficulties that afflict documentation.
 
-.. list-table::
-   :widths: 50 50
-   :header-rows: 1
-
-   * - How-to guides
-     - Tutorials
-   * - You are dealing with a user
-     - You are dealing with a learner
-   * - The user is responsible for asking the right questions
-     - The learner may not even have sufficient competence to ask the questions
-   * - The user decides what they want to know
-     - The teacher decides what the user needs to know
-   * - You can assume the user has sufficient competence to get themselves into and out of trouble
-     - You must assume the learner needs you to lead them all the way
-   * - The user is applying knowledge
-     - The learner is acquiring knowledge
-   * - The user needs to be shown
-     - The learner needs to be taught
-
-Notably, in most software documentation how-to guides tend to be well-written - much more well-written than tutorials.
-Software developers are often particularly good at writing them, because how-to guides follow the experience of a
-real-world user, and share the same task-focused perspective that a developer has when writing the software itself.
+See :ref:`tutorials-how-to` for an extended discussion of this distinction.
 
 
 ================

diff --git a/images/operation.jpg b/images/operation.jpg
diff --git a/images/suture.jpg b/images/suture.jpg
diff --git a/index.rst b/index.rst
@@ -86,7 +86,7 @@ Here is a video of a conference talk presenting the concepts encapsulated in Di
     </div>
 
 .. toctree::
-   :maxdepth: 0
+   :maxdepth: 1
    :hidden:
    :titlesonly:
 
@@ -95,7 +95,20 @@ Here is a video of a conference talk presenting the concepts encapsulated in Di
    How-to guides <how-to-guides>
    Reference <reference>
    Explanation <explanation>
-   introduction
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :titlesonly:
+
+   needs
+   Tutorials vs how-to guides <tutorials-how-to>
    how-to-use-diataxis
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :titlesonly:
+
    adoption
-   Development <development>
+   contact
diff --git a/introduction.rst → needs.rst b/introduction.rst → needs.rst
@@ -1,25 +1,13 @@
-Understanding user needs
+.. _needs:
+
+Understanding users' needs
 =============================
 
 Diátaxis isn't just a system for structuring documentation, it's a framework for understanding it, guiding the
 work of documentation authors, and assessing the quality of documentation. However its most obvious implication
 is for documentation structure.
 
 
-..  rst-class:: quote
-
-    At Gatsby we recently reorganized our open-source documentation, and the Diátaxis framework was our go-to resource
-    throughout the project. The four quadrants helped us prioritize the user’s goal for each type of documentation. By
-    restructuring our documentation around the Diátaxis framework, we made it easier for users to discover the
-    resources that they need when they need them.
-
-..  rst-class:: attribution
-
-  \- Megan Sullivan (`@meganesulli <https://twitter.com/meganesulli>`_)
-
-
-
-
 The problem of structure
 --------------------------
 
@@ -63,7 +51,6 @@ of documentation are laid out:
    :alt:
 
 
-------------
 
 Characteristics of documentation
 ----------------------------------------------------
@@ -72,38 +59,39 @@ Characteristics of documentation
 .. list-table::
    :widths: 16 21 21 21 21
    :header-rows: 1
+   :stub-columns: 1
 
    * - \
      - :ref:`Tutorials <tutorials>`
      - :ref:`How-to guides <how-to>`
      - :ref:`Reference <reference>`
      - :ref:`Explanation <explanation>`
-   * - \
+   * - what they do
      - introduce, educate, lead
      - guide, demonstrate
-     - states, describes, informs
-     - explains, clarifies, discusses
-   * - *answers the question*
+     - state, describe, inform
+     - explain, clarify, discuss
+   * - answers the question
      - "Can you teach me to...?"
      - "How do I...?"
      - "What is...?"
      - "Why...?"
-   * - *oriented to*
+   * - oriented to
      - learning
      - tasks
      - information
      - understanding
-   * - *purpose*
+   * - purpose
      - to allow the newcomer to get started
      - to show how to solve a specific problem
      - to describe the machinery
      - to explain
-   * - *form*
+   * - form
      - a lesson
      - a series of steps
      - dry description
      - discursive explanation
-   * - *analogy*
+   * - analogy
      - teaching a child how to cook
      - a recipe in a cookery book
      - a reference encyclopaedia article

diff --git a/requirements.txt b/requirements.txt
@@ -1,14 +1,3 @@
-# Key components
-
-Sphinx
-sphinx-autobuild
-furo
-pyenchant
-sphinxcontrib-spelling
-
-
-# Full list of pinned components, 2022-01-20
-
 alabaster==0.7.12
 Babel==2.9.1
 beautifulsoup4==4.10.0
@@ -34,6 +23,7 @@ snowballstemmer==2.2.0
 soupsieve==2.3.1
 Sphinx==4.4.0
 sphinx-autobuild==2021.3.14
+sphinx-design==0.0.13
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2
 sphinxcontrib-htmlhelp==2.0.0