Merge pull request #1030 from tahoe-lafs/3636.doc-toc-reorg

3636 Reorganize Tahoe-LAFS manual's main page

docs/README.txt

@@ -28,3 +28,47 @@ the resulting docs/_build/html/index.html in your web browser.
 Note that Sphinx can also process Python docstrings to generate API
 documentation. Tahoe-LAFS currently does not use Sphinx for this
 purpose.
+
+
+Organizing Tahoe-LAFS documentation
+-----------------------------------
+
+Tahoe-LAFS documentation has been a mishmash of many things that are
+useful to many people, with little organization, and, as a result,
+confusing and hard-to-approach.  We are working on improving this.
+
+It is reasonable to expect that documentation files in "docs"
+directory will serve different and possibly overlapping groups of
+readers, so the top-level sections are organized based on the likely
+needs of those almost-distinct groups.  We have:
+
+  (a) New and experienced users of Tahoe-LAFS, who mainly need an
+      operating manual to the software.  Notes under the section
+      titled "Getting Started with Tahoe-LAFS" will be the most useful
+      to them.
+
+  (b) Project contributors, both new and experienced.  This group
+      includes developers, issue reporters, and documentation writers.
+      It will help this group to have the project's processes and
+      guidelines written down.  The section titled "Contributing to
+      Tahoe-LAFS" is meant to be useful for this group.
+
+  (c) Those who want to know various implementation details about the
+      project.  This group might include people who are mainly curious
+      and those who want change things.  We could expect an overlap
+      between members of group (a) who want to know more and members
+      of group (b).  The sections titled "Tahoe-LAFS in Depth" and
+      "Specifications" could be of interest to them.
+
+  (d) There's also the broader community.  This includes people with a
+      general interest in Tahoe-LAFS project, and people from groups
+      both (a) and (b).  They will find "Notes of Community Interest"
+      useful.
+
+When you add new content or remove old content to Tahoe-LAFS docs, it
+would be helpful to organize your changes with the above-stated groups
+of readers in mind.
+
+This directory also contains old notes that are mainly of historical
+interest, under the section titled "Notes of Historical Interest".
+Those could be removed someday, after sufficient consideration.

docs/index.rst

@@ -5,68 +5,88 @@ Tahoe-LAFS
 .. Please view a nicely formatted version of this documentation at
    http://tahoe-lafs.readthedocs.io/en/latest/
 
-Contents:
+   Please see the notes under "Organizing Tahoe-LAFS documentation" in
+   docs/README.txt if you are editing this file.
+
+Tahoe-LAFS is a Free and Open decentralized storage system.
+It distributes your data across multiple servers.
+Even if some of the servers fail or are taken over by an attacker,
+the entire file store continues to function correctly,
+preserving your privacy and security.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :caption: Getting Started with Tahoe-LAFS
 
    about-tahoe
+
    Installation/install-tahoe
    Installation/install-on-windows
    Installation/install-on-linux
    Installation/install-on-desert-island
-   running
-   magic-wormhole-invites
-   configuration
-   architecture
 
+   running
+   configuration
+   servers
    frontends/CLI
-   frontends/webapi
    frontends/FTP-and-SFTP
    frontends/download-status
-
+   magic-wormhole-invites
+   anonymity-configuration
    known_issues
-   contributing
-   CODE_OF_CONDUCT
-   release-checklist
-   gpg-setup
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Tahoe-LAFS in Depth
+
+   architecture
+   gpg-setup
    servers
    managed-grid
    helper
    convergence-secret
    garbage-collection
-
-   backdoors
-   donations
-   accepting-donations
-   expenses
-   cautions
+   filesystem-notes
+   key-value-store
+   frontends/webapi
    write_coordination
+   cautions
    backupdb
-
-   developer-guide
-   ticket-triage
-
-   anonymity-configuration
-
    nodekeys
    performance
    logging
    stats
 
-   debian
-   build/build-pyOpenSSL
+.. toctree::
+   :maxdepth: 1
+   :caption: Specifications
 
    specifications/index
    proposed/index
-   filesystem-notes
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contributing to Tahoe-LAFS
+
+   contributing
+   CODE_OF_CONDUCT
+   developer-guide
+   ticket-triage
+   release-checklist
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Notes of Community Interest
+
+   backdoors
+   donations
+   accepting-donations
+   expenses
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Notes of Historical Interest
+
    historical/configuration
-   key-value-store
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   debian
+   build/build-pyOpenSSL

newsfragments/3636.documentation

@@ -0,0 +1 @@
+Tahoe-LAFS manual's table of contents page has been reorganized.