suggested improvements to quick start instructions #1882

New Issue

tahoe-lafs · 2012-12-01T22:35:08Z

rcarz commented

2012-12-01 22:35:08 +00:00

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.

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.

tahoe-lafs added the

labels 2012-12-01 22:35:08 +00:00

tahoe-lafs added this to the undecided milestone 2012-12-01 22:35:08 +00:00

zooko commented

2013-09-26 17:12:25 +00:00

This was a duplicate of #1024. However, the initial post on this ticket has a lot of useful ideas, and I hope people looking at #1024 come and read it! rcarz: if you have some notes from your experiences that you could post, that would be helpful!

zooko added the

duplicate

label 2013-09-26 17:12:25 +00:00

zooko closed this issue

2013-09-26 17:12:25 +00:00

Sign in to join this conversation.