launchpad-reviewers team mailing list archive

[Jürgen Gmach <mp+415442@xxxxxxxxxxxxxxxxxx>]

Jürgen Gmach has proposed merging ~jugmac00/launchpad:apply-diataxis-framework into launchpad:master.

Commit message:
Introduce the Diátaxis documentation framework

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~jugmac00/launchpad/+git/launchpad/+merge/415442
-- 
Your team Launchpad code reviewers is requested to review the proposed merge of ~jugmac00/launchpad:apply-diataxis-framework into launchpad:master.

diff --git a/doc/email.rst b/doc/email.rst
index d28d8e9..12d19f7 100644
--- a/doc/email.rst
+++ b/doc/email.rst
@@ -1,4 +1,4 @@
-Launchpad and Email
+Launchpad and email
 ===================
 
 Quicker interactive testing
diff --git a/doc/guides/architecture.rst b/doc/explanation/architecture.rst
similarity index 94%
rename from doc/guides/architecture.rst
rename to doc/explanation/architecture.rst
index cc5c143..aff1307 100644
--- a/doc/guides/architecture.rst
+++ b/doc/explanation/architecture.rst
@@ -1,5 +1,5 @@
 ===================
-Architectural Guide
+Architectural guide
 ===================
 
 All the code we write will meet these values to a greater or lesser degree.
@@ -37,7 +37,7 @@ Launchpad is moving to a `services-based design
 <https://dev.launchpad.net/ArchitectureGuide/Services>`_.  This is intended
 to faciliate achieving many of the goals from this guide.
 
-The :doc:`Python style guide <python>` specifies coding style guidelines.
+The :doc:`Python style guide <../how-to/python>` specifies coding style guidelines.
 
 Values
 ======
diff --git a/doc/pip.rst b/doc/explanation/pip.rst
similarity index 100%
rename from doc/pip.rst
rename to doc/explanation/pip.rst
diff --git a/doc/running-details.rst b/doc/explanation/running-details.rst
similarity index 100%
rename from doc/running-details.rst
rename to doc/explanation/running-details.rst
diff --git a/doc/faq.rst b/doc/faq.rst
index d90de6a..d354ec7 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -53,11 +53,6 @@ new users, create a new account and check the local mailbox, or check
 
 .. _create-additional-user-accounts-dev-env:
 
-How do I create additional user accounts in the dev environment?
-================================================================
-You can create a new account using the ``utilities/make-lp-user`` script and log
-in to that account at ``https://launchpad.test``.
-
 My database permissions keep getting deleted!
 =============================================
 
diff --git a/doc/guides/exceptions.rst b/doc/how-to/exceptions.rst
similarity index 95%
rename from doc/guides/exceptions.rst
rename to doc/how-to/exceptions.rst
index a1130a6..4ba5e93 100644
--- a/doc/guides/exceptions.rst
+++ b/doc/how-to/exceptions.rst
@@ -1,6 +1,6 @@
-==================
-Exception Handling
-==================
+========================
+How to handle exceptions
+========================
 
 Catching exceptions
 ===================
diff --git a/doc/how-to/new-user.rst b/doc/how-to/new-user.rst
new file mode 100644
index 0000000..4bbc127
--- /dev/null
+++ b/doc/how-to/new-user.rst
@@ -0,0 +1,5 @@
+How do I create additional user accounts in the dev environment?
+================================================================
+
+You can create a new account using the ``utilities/make-lp-user`` script and log
+in to that account at ``https://launchpad.test``.
diff --git a/doc/guides/python.rst b/doc/how-to/python.rst
similarity index 97%
rename from doc/guides/python.rst
rename to doc/how-to/python.rst
index f2ede1a..6dd7e73 100644
--- a/doc/guides/python.rst
+++ b/doc/how-to/python.rst
@@ -1,6 +1,6 @@
-==================
-Python Style Guide
-==================
+========================
+How to style Python code
+========================
 
 This document describes expected practices when writing Python code.  There
 are occasions when you can break these rules, but be prepared to justify
diff --git a/doc/running.rst b/doc/how-to/running.rst
similarity index 88%
rename from doc/running.rst
rename to doc/how-to/running.rst
index 1a95857..8f3379b 100644
--- a/doc/running.rst
+++ b/doc/how-to/running.rst
@@ -1,6 +1,6 @@
-=================
-Running Launchpad
-=================
+===============================
+How to set up and run Launchpad
+===============================
 
 .. note::
 
@@ -150,7 +150,7 @@ Then:
    $ curl https://git.launchpad.net/launchpad/plain/utilities/rocketfuel-setup >rocketfuel-setup
 
 Read through the rocketfuel-setup script at this point and make sure you're
-OK with what it's going to do.  (See :doc:`running-details` if you want to
+OK with what it's going to do.  (See :doc:`../explanation/running-details` if you want to
 know more.)
 
 .. code-block:: shell-session
diff --git a/doc/security.rst b/doc/how-to/security.rst
similarity index 97%
rename from doc/security.rst
rename to doc/how-to/security.rst
index f4309af..2ffacb4 100644
--- a/doc/security.rst
+++ b/doc/how-to/security.rst
@@ -1,5 +1,5 @@
-Security Policy in Launchpad
-============================
+How to handle security policies
+===============================
 
 Zope 3 is a security-aware framework that makes it possible to develop complex
 applications with security policies that closely resemble the reality that the
diff --git a/doc/guides/tests.rst b/doc/how-to/tests.rst
similarity index 98%
rename from doc/guides/tests.rst
rename to doc/how-to/tests.rst
index 0615ae6..ff876dc 100644
--- a/doc/guides/tests.rst
+++ b/doc/how-to/tests.rst
@@ -1,6 +1,6 @@
-=================
-Tests Style Guide
-=================
+==================
+How to style tests
+==================
 
 This page documents conventions for our Launchpad tests.  Reviewers make
 sure that code merged is documented and covered by tests.  Following the
diff --git a/doc/index.rst b/doc/index.rst
index 2fa2b59..4548740 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -22,34 +22,28 @@ Overview
    values
    faq
 
-Tutorials
-=========
+How-to Guides
+=============
 
 .. toctree::
    :maxdepth: 1
 
-   running
+   how-to/running
+   how-to/python
+   how-to/tests
+   how-to/exceptions
+   how-to/security
+   how-to/new-user
 
-Guides
-======
+Explanation
+===========
 
 .. toctree::
    :maxdepth: 1
 
-   guides/architecture
-   guides/python
-   guides/tests
-   guides/exceptions
-
-Technical
-=========
-
-.. toctree::
-   :maxdepth: 1
-
-   running-details
-   pip
-   security
+   explanation/running-details
+   explanation/architecture
+   explanation/pip
 
 Possibly out-of-date
 --------------------
diff --git a/doc/strategy.rst b/doc/strategy.rst
index 7a14fe5..a248d0d 100644
--- a/doc/strategy.rst
+++ b/doc/strategy.rst
@@ -1,5 +1,5 @@
 ==================
-Launchpad Strategy
+Launchpad strategy
 ==================
 
 *We want to make Ubuntu the world’s best operating system. To do this, we need
diff --git a/doc/values.rst b/doc/values.rst
index 2647f97..6e1a252 100644
--- a/doc/values.rst
+++ b/doc/values.rst
@@ -1,5 +1,5 @@
 ================
-Launchpad Values
+Launchpad values
 ================
 
 Whenever we are thinking about what Launchpad should be, or how we should