[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:  closed
     Priority:  normal         |  Milestone:  undecided
    Component:  documentation  |    Version:  1.9.2
   Resolution:  duplicate      |   Keywords:  docs
Launchpad Bug:                 |
-------------------------------+-----------------------
Changes (by zooko):

 * status:  new => closed
 * resolution:   => duplicate


Old description:

> 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.

New description:

 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.

--

Comment:

 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!

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