[tahoe-lafs-trac-stream] [Tahoe-LAFS] #1024: introductory docs are confusing and off-putting

[Tahoe-LAFS]

#1024: introductory docs are confusing and off-putting
-------------------------+-------------------------------------------------
     Reporter:  zooko    |      Owner:  zooko
         Type:  defect   |     Status:  new
     Priority:  major    |  Milestone:  soon
    Component:           |    Version:  1.6.1
  documentation          |   Keywords:  docs install packaging website
   Resolution:           |  tahoe-run
Launchpad Bug:           |
-------------------------+-------------------------------------------------

Comment (by zooko):

 Here's another data point that
 [source:trunk/docs/running.rst at bb13bba2a5092c6cf224cb58a4808f2aa1cb2a61
 the current running.rst] is too complicated for people — even technical
 computer programmers — to wade through in order to launch the client:

 https://twitter.com/sanjay/status/595602503275798528

 I have three ideas about this.

 First one is get a UX expert like Gus to brainstorm what the user
 experience ''should'' ideally be, starting from the install process.

 My second idea is to look at `running.rst` and see what are the steps that
 it is instructing the user to do and ''not Wizardify those steps'' but
 ''remove those steps''. We can in some cases remove the steps entirely so
 that the thing Just Works without that step, and in other cases we can
 move those steps from the basic introductory docs to advanced docs,
 because those steps are optional.

 The first such step that we might be able to optimize out of `running.rst`
 is passing the introducer furl from the introducer to the client. This is
 potentially optimize-outable because of [ticket:403 #403 grid
 identifiers]. I think that basically means stuffing the introducer furl
 into the file/dir caps, but with some optimizations so it doesn't bloat
 the caps as much. Brian: what do you think? Could gridids optimize out one
 of the steps from `running.rst`?

 The next such step is to set the default `K`, `M`, and `H` to 1 and remove
 mention of `K`, `M`, and `H` from the introductory doc. Running more than
 one server, or using erasure coding will be advanced features that people
 can level-up to after the understand the basic `K=M=H=1` deployment. (This
 is ticket [ticket:1082 #1082 default servers-of-happiness=7 prevents
 single-server use case from working "out of the box"].)

--
Ticket URL: <https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1024#comment:30>
Tahoe-LAFS <https://Tahoe-LAFS.org>
secure decentralized storage