[tahoe-lafs-trac-stream] [tahoe-lafs] #1882: suggested improvements to quick start instructions

[tahoe-lafs]

#1882: suggested improvements to quick start instructions
---------------------------+---------------------------
 Reporter:  rcarz          |          Owner:  marlowe
     Type:  task           |         Status:  new
 Priority:  normal         |      Milestone:  undecided
Component:  documentation  |        Version:  1.9.2
 Keywords:  docs           |  Launchpad Bug:
---------------------------+---------------------------
 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.

-- 
Ticket URL: <https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1882>
tahoe-lafs <https://tahoe-lafs.org>
secure decentralized storage