suggested improvements to quick start instructions

[rcarz]

The quick start instructions are very brief and there's a lot of handwaving. I suggest thinking of practical use cases for Tahoe and changing quick start instructions to walk new users through the process.

For example, current documentation is broken into three parts: quickstart, running, and configuration. There's no clear flow or obvious process for actually using Tahoe. The quickstart page outlines the process of installing Tahoe, but a person following that isn't really starting anything.

The running page references a non-existent test grid. And there's no clear process for how to use Tahoe in any particular way. The page essentially just details how to start it with some handwaving over the components. The configuration page is great for a reference but it doesn't clearly help a new user get started.

I really like documentation this Linux distribution uses to guide new users through the install process (​http://www.gentoo.org/doc/en/handbook/handbook-x86.xml). Clicking through the manual you'll notice a clear flow with explicit commands and explanations about what you're doing and why that step is necessary.

Obviously in the case of Tahoe such detail (especially in regards to third party software) isn't necessary. I would suggest detailing the installation process with specific use cases in mind. Quick-start should be "how do I get a simple client running quickly?" and then there would be more detailed chapters for storage nodes, introducer, helpers, and etc. These pages should included necessary configuration settings, including any relevant operating system and/or network configuration that's needed. (ex: What ports do you open in a firewall? A new user doesn't necessarily know which ports are necessary.)

Unfortunately I'm not sure I know enough about Tahoe yet to contribute valuable documentation. I'll keep notes though as I start using it more.