id	summary	reporter	owner	description	type	status	priority	milestone	component	version	resolution	keywords	cc	launchpad_bug
1882	suggested improvements to quick start instructions	rcarz	marlowe	"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."	task	closed	normal	undecided	documentation	1.9.2	duplicate	docs