ExternalVendorCode/tahoe-lafs
1
0
Fork 0
mirror of https://github.com/tahoe-lafs/tahoe-lafs.git synced 2024-12-20 21:43:09 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Manual: add notes about docs organization

Browse Source
This commit is contained in:
Sajith Sasidharan 2021-10-19 14:09:36 -04:00
parent 40f4c0ea85
commit aa391be5f8
No known key found for this signature in database
GPG Key ID: 0C6DA6A29D5F02BA
1 changed files with 43 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
docs/README.txt
View File

@ -28,3 +28,46 @@ 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. Sections on "Introduction"
and "Using 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.