3636 Reorganize Tahoe-LAFS manual's main page

[sajith]

Ticket is https://tahoe-lafs.org/trac/tahoe-lafs/ticket/3636.

I humbly submit that the manual page in this version is hard to navigate, and this version is easier.

Changes:

• Some top-level categories have been added (running, tech notes, specs, notes for contributors, etc.)
• Rearranged order of documents to fit the categories mentioned above. (No document should be missing as a result of this reordering, or Sphinx would complain about them missing from the toctree.)
• Depth of the toctree has been limited to 1. A depth of 2 is harder to navigate.
• Removed "Indices and tables", as it does not do anything presently. It must have been added by sphinx-autogen when generating the new Sphinx doc project.

[YashNayani]

I don't think it's necessary to provide a blurb on the Index page.

[sajith]

I would remove the blurb if there's some reasoning on why it is unnecessary. :-)

As to why it is probably necessary: I'd imagine that a casual reader (such as someone visiting https://tahoe-lafs.readthedocs.io for the first time) would want to know, in a glance, just what it is that they are looking at.

[YashNayani]

I think the Index page can just give people insight into where they can find information. If it's a casual/first-time reader, they most certainly will visit the "Welcome to Tahoe-LAFS" page. And they are bound to read the same/similar intro paragraphs, which IMO, is undesirable.

[sajith]

I think the blurb will provide motivation to read further. Other paragraphs in "Welcome to Tahoe-LAFS" page doesn't seem to be repeating the same thing.

[YashNayani]

I would recommend renaming this to "Getting Started with Tahoe-LAFS" and include installation, and basic configuration articles". The "Using Tahoe-LAFS" section can cater to parallel stuff like some of the stuff you have mentioned (anonymizing network,CLI commands, etc).

[sajith]

I'm not sure about this. Introduction is, well, an introduction, and the rest (installing, building, configuring, running, other usage notes) should be under "Using Tahoe-LAFS".

Please take a look at this build of the docs. Would you still re-arrange it that way?

[YashNayani]

Yes, thanks for the new build. I would definitely re-arrange it that way. I am not a big fan of having an Introduction section. Feels very retro to me, like we're documenting for print media. A lot of cloud tech companies are still bound to this ideology. See "The grand theory of Documentation". I am not a big fan of this and believe this does not work with writing for the internet. Instead, we can cut the clutter and just have two types of articles "About Tech1/Feature1". How to do "Tech1/Feature1".

Sorry about the tangent, but that is the reason I don't want to call it Introduction is because for people to read introductions they have to be motivated/excited about what they're reading about. 95% of the time the user is at help because they couldn't make stuff work or just want to learn how to do specific things. And that's the reason I want all titles to (somewhat) be verbs. i.e.,

• About Tahoe-LAFS > Welcome to Tahoe-LAFS
• Getting Started > Introduction
• Installing Tahoe-LAFS > Installation Guide
• Running Tahoe-LAFS > How to Run Tahoe-LAFS

Of course, there are going to be some theoretical articles, but that's why we will have "About ..." articles; where we will actively drive the user to a "How-to" article.

About Nodes will (potentially) redirect users to:

• Configuring a Tahoe-LAFS node
• Running Tahoe-LAFS

I hope that makes sense.

[sajith]

@YashNRam13 Made a change in f39d765. The other changes you describe will have to be separate pull requests, right?

[YashNayani]

I've removed this article and another one (OS-X packaging) in my PR. I've also made some changes to Index file (brought all installation guides at the top). I am not sure how we resolve conflicts which will arise.

[sajith]

I have updated the PR.

[YashNayani]

Awesome!

[YashNayani]

I would rename this to "About Tahoe-LAFS" and if there are many parallel articles with varying complexity, then maybe "About Tahoe-LAFS in depth".

[YashNayani]

Wouldn't desert-island be a part of installation?

[sajith]

That is actually geared towards Tahoe-LAFS hackers, according to the document itself:

Here’s the story: you leave for the airport in an hour, you know you want to do some Tahoe hacking on the flight. What can you grab right now that will let you install the necessary dependencies later, when you are offline?

I don't think it should be part of installation. In the current commit (d91638d) after merging master, it is under installation, but I'll move it back under developer notes if you agree about that choice.

[YashNayani]

I think we can keep it near installation. We need to rework it along the lines of "Installing Tahoe-LAFS completely offline". But until we get to revamping that, we can keep it under developer notes.

[YashNayani]

I really like this organization of the index page. Everything is more searchable and structured.

[sajith]

Thanks. :-)

[May-Lee]

@exarkun were your requested changes addressed? @sajith @YashNRam13 does anyone object if I optimistically merge this PR?

[exarkun]

@exarkun were your requested changes addressed? @sajith @YashNRam13 does anyone object if I optimistically merge this PR?

I would like to see my top-level review comment addressed:

Taking in the bigger picture, it would be nice to have the organizing principles for this index recorded - perhaps in the index itself. If knowing those principles would help readers navigate the index, great, let's make the information a visible part of the docs. If it is really only useful to future documentation maintainers, we can still include it as rst comments.
The PR description seems to contain some of the organizing principles, so including those would be a start. It would be nice if every content change being made could be traced directly to a documented organizing principle, though, so the PR description may just be a start.

It doesn't matter to me very much what those principles are but I don't see how we can collaborate on the documentation without a shared understanding of them.

[YashNayani]

Taking in the bigger picture, it would be nice to have the organizing principles for this index recorded - perhaps in the index itself. If knowing those principles would help readers navigate the index, great, let's make the information a visible part of the docs. If it is really only useful to future documentation maintainers, we can still include it as rst comments.

@exarkun I agree with you; the documenting/organization principles for this index need to be recorded. However, I do not think that it needs to be realized by adding comments in the index itself. I'll be building off @sajith 's beautiful index here in this PR as I make changes to the documentation. We can then later work on a style guide which accommodates for this index's organization principles.

The PR description seems to contain some of the organizing principles, so including those would be a start. It would be nice if every content change being made could be traced directly to a documented organizing principle, though, so the PR description may just be a start.

The PR description does have some of the principles, but they are highly subject to change as I find out more and more about Sphinx's and Tahoe's capabilities. As a stop-gap solution until we come up with our very own documentation style-guide; we can follow the WriteTheDocs Style Guidelines. This is not tailored for us but accommodates for everything.

I've created a new trac ticket for the style guide. @exarkun if this is satisfactory, I'd love for this PR to be merged so that I can use the new index as a base for modifications.

[sajith]

@YashNRam13 @exarkun @May-Lee Apologies for abandoning this PR for such a long time. Fault is all mine: I have been away, then busy with other things, then away again, and then busy again.

I have added some notes to docs/README.txt about organizing the manual's table of contents with different audiences in mind (commit aa391be), and added a note to docs/index.rst about the notes in docs/README.txt (commit 2b2c1e0). I imagine that the almost-distinct groups of readers mentioned in this update will benefit from this round of re-organization of our docs, and I imagine that we will want to organize the manual based on the needs of those different groups of readers.

Obviously what I imagine to be true is up for debate. :-)