diff --git a/docs/README.txt b/docs/README.txt index b571a2077..a4bcef7a7 100644 --- a/docs/README.txt +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index 41fdd9f7a..47a9bd0e5 100644 --- a/docs/index.rst +++ b/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 diff --git a/newsfragments/3636.documentation b/newsfragments/3636.documentation new file mode 100644 index 000000000..74f851268 --- /dev/null +++ b/newsfragments/3636.documentation @@ -0,0 +1 @@ +Tahoe-LAFS manual's table of contents page has been reorganized.