[tahoe-lafs-trac-stream] [tahoe-lafs] #1024: introductory docs are confusing and off-putting
tahoe-lafs
trac at tahoe-lafs.org
Thu Sep 26 17:11:36 UTC 2013
#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: |
-------------------------+-------------------------------------------------
Old description:
> Glyph offered a lot of detailed criticism of "the introductory docs" --
> install.html, running.html, and using.html.
> My general take-away from this is:
> 1. Let the introductory docs first show how to share a file using a live
> test grid.
> 2. Then, say why you might want to run your own gateway
> (confidentiality, integrity), and how to acquire and build Tahoe-LAFS
> software and run a gateway.
> 3. Then, say why you might want to run your own storage servers
> (availability, reliability, provisioning), and how to run an introducer
> and storage servers.
>
> * Along the way you assiduously avoid saying anything that is not
> necessary to the motivational and instructional bits. No terminology, no
> explanations. Just why and how.
> * Likewise, carefully eliminate all mention of alternatives: alternative
> UIs that are not the WUI, "tahoe run" vs "tahoe start", different ways to
> install if "install.html" doesn't work -- all of these get segregated off
> to another document which people might eventually find if the basic
> quickstart doesn't work for them.
> * Likewise, no mention of optional features which are not necessary to
> do the basic filesharing use case, such a providing a nickname for your
> nodes.
> * Along the way we need to provide "breadcrumbs" which give the user
> confidence that they are still on the right track. Glyph suggests
> screenshots. Sounds like a good idea!
> * After the howto is finished you can point to another introductory doc
> which is the "what" -- a simple summary of Tahoe-LAFS components and
> behavior. There are some users, like Glyph and my brother Josh, who
> really hate having that stuff mixed into their "why and how" howto, but
> there are other users who refuse to follow the why-and-how howto until
> they've learned the what-it-is overview. We need to address both types of
> reader.
>
> By the way: I'm concerned about InstallDetails. It seems that some users
> move from install.html to InstallDetails and then have troubles which
> they would not have if they followed install.html. I've already put a
> note in install.html claiming (more or less justifiably) that
> install.html works on Windows, Mac, Linux, etc. I think we should also
> put a note at the top of InstallDetails urging people to try install.html
> first and not to look at InstallDetails unless install.html doesn't work
> for them. (And to report a bug if that is the case.)
>
> An open issue in my mind is what to do about the firewall/NAT issue. We
> used to not-mention it in running.html, but enough people had problems
> with it that we added a paragraph about it to running.html. However,
> every sentence added to running.html hurts. Brevity is paramount. I think
> I'll move those instructions to a different wiki page (not InstallDetails
> because I'm trying to steer people away from InstallDetails) and put one
> sentence in using.html that says "If the welcome page shows that some of
> your servers are not connected to your gateway, like this [SCREENSHOT],
> then perhaps you have a problem with firewalls or NAT -- see
> FirewallsAndNat for how to fix that."
>
> Excerpts from IRC:
> {{{
> <glyph> zooko: to be fair, Tahoe *is* a pain in the ass to use, it's just
> not
> a pain in the ass to use because of the encryption :)
> <zooko> glyph: touché
> [12:35]
> <zooko> glyph: now tell me something more specific!
> <glyph> zooko: the number of terms I have to learn about in order to even
> _try_ to set it up is way too much cognitive laod
> <zooko> glyph: Aha! Very useful feedback. Thanks! Hm.
> [12:36]
> ...
> <glyph> zooko: but it's not like I can read install.html and go; all
> install.html gets me is a terminal window spewing some logs
> <glyph> I have to read
> http://allmydata.org/source/tahoe-lafs/trunk/docs/install.html
> and
> http://allmydata.org/source/tahoe-lafs/trunk/docs/running.html
> and
> http://allmydata.org/source/tahoe-lafs/trunk/docs/using.html
> <zooko> glyph: so, your objection sounds very plausible to me -- I
> wouldn't be
> surprised if our docs inadvertently mention too many neutron flux
> capacitors.
> <zooko> But that particular set of three that you just posted are the one
> that
> are intended *not* to have.
> <zooko> So I'm wondering if it is actually those ones that give you that
> cognitive overload, or other ones.
> [12:40]
> <zooko> glyph: it was my idea to split that into three web pages. Perhaps
> I
> suck at web design.
> <glyph> zooko: there are also no pictures on those pages
> <glyph> zooko: have you ever read cyli's tutorial on
> Twisted+Divmod/Windows
> development? :)
> [12:42]
> <zooko> glyph: huh? What do you want, screenshots? Or network diagrams
> like
> http://secorp.net/images/network-and-reliance-topology.png
> <zooko> glyph: I think I looked at it a while back. I'll look it up.
> <zooko> You're recommending it as a good example of a tutorial?
> <glyph> zooko: screenshots. I want confirmation that I have followed the
> steps correctly and that what I'm seeing on my screen is an
> indication
> of success.
> <glyph> If you can do that without screenshots, that's okay too
> <zooko> glyph: hm. Okay, we can add a screenshot of the WUI to
> http://allmydata.org/source/tahoe-lafs/trunk/docs/using.html
> <zooko> glyph: is the part about "clients, servers, and introducers" on
> http://allmydata.org/source/tahoe-lafs/trunk/docs/running.html
> part
> where you tend to fall off of the text?
> <glyph> zooko: also, I want a tutorial that goes deeper
> <zooko> That's the part that we could optimize out if someone else was
> already
> running a server grid for you...
> <glyph> zooko: yes. The term "introducer", in particular, is unclear
> <zooko> glyph: ok
> <glyph> zooko: I *sort* of understand its purpose, but to a naive user it
> really sounds like some extraneous piece of junk which you really
> don't need
> <glyph> zooko: let me get to my main point though
> <glyph> (although the presence of the string "tub" without any
> explanation of
> what a "tub" is doesn't help either)
> <zooko> Thanks for that note, too. I'll put all of this in the ticket.
> <glyph> the real problem is that I don't really give a crap about
> anything
> that this documentation is showing me how to do
> <glyph> I already know how to create folders
> <glyph> File->New Folder in Finder
> [12:47]
> <glyph> done
> <glyph> I didn't need to "construct a client node" or "construct an
> introducer"
> <glyph> in order to do that
> <glyph> what I really want the setup documentation to take me through is
> the
> simplest, fastest possible path to share a file with someone else
> <zooko> Ah!
> <glyph> I want to learn how to share files with tahoe
> <glyph> I am actively un-interested in constructing an introducer tub
> node
> flux capacitor
> <glyph> so the setup documentation should take me through how to do it,
> and it
> should take me how to do it ONE way
> <warner> glyph: go to http://testgrid.allmydata.org:3567/
> <warner> upload a file into the "Upload a file" box
> [12:49]
> <zooko> So, there's a big difference between using someone else's pre-
> existing
> servers and setting up your own.
> <zooko> Maybe the introductory docs could show you that -- the way to
> share a
> file using testgrid.allmydata.org --
> <zooko> and then have a subsequent section explaining how to set up your
> own
> grid.
> <warner> then copy the resulting "Download link:" URL and give it to the
> person you want to get the file
> <secorp> Here's a files for example:
> <glyph> okay. maybe I want to set up my own. Do I? I don't know! What
> does
> setting up my own get me? I'm pretty sure that when I upload my
> ssh
> key to that form, warner will steal it and use it to get hot
> insider
> stock tipzzzz
> <secorp>
> http://testgrid.allmydata.org:3567/file/URI:CHK:azzp7eyzixkstgxd2ppejm3smu:laz6zt6fdg24fs3agoezhgahqoyi6pcwzd2grakl7orbzlxjpydq:3:10:252/@@named=/notice.txt
> <glyph> so I want to run some secure software on my computer
> [12:50]
> <secorp> Sorry, "a file"
> <idnar> is testgrid.allmydata.org as reliable as, say, dropbox.com
> though?
> <zooko> idnar: ha
> <idnar> or does that matter?
> <zooko> idnar: for the purpose of introductory doc, we'll point at some
> demo
> grid.
> <idnar> (I haven't read any Tahoe-LAFS documentation whatsoever, just
> lurked
> in the channel)
> <zooko> So that Glyph can try sharing a file and, seeing that it worked,
> go
> ahead and read the next page of the doc.
> [12:51]
> <zooko> Even though the demo grid is unreliable and warner reads all the
> confidential files shared thereby.
> <glyph> warner: right, so that's not very interesting to me
> <zooko> But then the next paragraph of the doc explains why you might
> want to
> run your own instead of using that one.
> <glyph> I want to securely share some files on a private network with my
> friends
> <zooko> glyph: right, and that's where the current install.html starts.
> <glyph> zooko: okay. So, install.html isn't too bad. It leaves out the
> part
> where I have to fight with setuptools for two hours because it
> wanted
> to corrupt my /Library/Frameworks/Python.framework directory, but
> arguably that's my own fault.
> <glyph> zooko: the problems start in running.html
> <glyph> in fact I think the problems start in the first sentence
> <zooko> glyph: no you are wrong!
> <zooko> install.html never told you to install anything into your system
> folders.
> <glyph> "This is how to run a Tahoe client *OR* a complete Tahoe grid"
> * zooko double-checks...
> <warner> I wonder if the verbs we use to name those documents are
> misleading..
> [12:54]
> <zooko> Yes. There is no "installing".
> <zooko> Ah good point.
> <zooko> There is no "installing" in "install.html".
> <glyph> Perhaps tahoe wanted to break my system because of InstallDetails
> <glyph> it's been a while since I actually did this
> <warner> tahoe runs fine out of the source tree
> [12:55]
> <glyph> but running.html is trying to tell me too much stuff
> <warner> ./bin/tahoe $command
> <zooko> Yes, I have mixed feelings about InstallDetails.
> <zooko> It seems people frequently skip install.html for one reason or
> another,
> <zooko> go to InstallDetails, and then have all sorts of problems.
> <zooko> Anyway, what were you saying about the worst problems being in
> running.html
> * zooko looks at running.html
> [12:56]
> <glyph> I really don't care about creating, stopping and starting nodes;
> I
> don't care what a tahoe network is made of. I am looking for a
> very
> linear set of instructions telling me how to get one particular
> thing
> done.
> <warner> glyph: does "./bin/tahoe --version" work for you?
> <glyph> warner: Yes.
> <zooko> Yes, running.html has grown.
> <warner> great, that's most of the battle won
> <zooko> Communally edited docs tend to grow more than to shrink...
> <zooko> glyph: specifically, I originally wrote running.html more along
> the
> lines of what you are asking for.
> [12:57]
> <glyph> What I really want (especially with my "very impatient but
> slightly
> curious user" hat on) is something that says "do this. then do
> that.
> then do this other thing. Now you can securely share files with
> your
> friends, if they do this, and then do that!"
> <zooko> And then others came along and said "Hey this doesn't have enough
> explanation" and added some details.
> <zooko> So I think after I copy some of your comments to a trac ticket
> I'll go
> prune it back again...
> <warner> glyph: first step, choose a machine that all of your potential
> clients can access, and make sure that "./bin/tahoe --version"
> works
> on it, and pick a working directory, and run
> ".../path/to/bin/tahoe
> create-introducer WORKDIR/introducer" and also ".../tahoe start
> WORKDIR/introducer"
> <glyph> then at the _end_ of the document, or _after_ the steps where I
> do
> stuff that gets something set up, you can tell me "You just set
> up an
> introducer node. The purpose of this thing is to ..."
> <warner> then you need at least one storage server, which can be on the
> same
> machine as the introducer
> [12:58]
> <glyph> "getting everybody talking to each other" is simultaneously too
> much
> detail (why do I care what this thing does? I just want to share
> a
> file!) and not enough (isn't "getting everybody talking to each
> other"
> what like, sockets, and ethernet cables, are for?)
> <warner> second step: same as above, but use "create-node
> WORKDIR/storage" and
> "start WORKDIR/storage"
> [12:59]
> <warner> glyph: ah, so now the instructions that you want have bifurcated
> <glyph> warner: I want to read about all of these things, but I want to
> read
> about the conceptual explanation _after_ I've got something
> working
> with my friends
> [13:00]
> <warner> there is one audience, like you, who is well aware of just how
> annoying the modern internet is, and how it's NP-Hard to get one
> computer to send a message to another
> <glyph> similarly, I don't really care about multiple UIs; it should
> really
> just show me the best one (which, sadly, really ought to be the
> FUSE
> one)
> <warner> to whom "make sure your server has a publically-routable IP
> address"
> makes sense, even if the need to say that makes them cry
> <zooko> I think this is the worst patch to running.html:
> http://tahoe-lafs.org/trac/tahoe-
> lafs/changeset/4044/docs/running.html
> [13:01]
> <glyph> warner: okay so, step 1, include vertex in foolscap and do NAT
> punching so you don't need any of that config nonsense ;)
> <warner> the other audience doesn't want to know about this pain, and
> wants to
> believe that the little radar-shaped wifi icon means they can
> see the
> whole world
> <zooko> A user, Sam Mason, had trouble with running.html and submitted a
> diff
> adding all these details.
> <zooko> glyph: the FUSE one doesn't work. The one default ui will be the
> WUI
> for the next release or so.
> <glyph> Seriously though, the important thing is just to say "do this,
> then do
> that", and if I'm a smarty pants who thinks that I know better
> what
> port number my firewall should be pointing at Tahoe I can change
> it,
> but I probably don't
> [13:02]
> <warner> glyph: you know full well that won't be enough: which QSP do you
> sign
> up with? how do you get an account with them? what's a QSP
> anyway?
> making it at least step -3 or so :)
> <glyph> warner: yes yes, it was a joke :)
> <warner> yeah, I know :)
> <zooko> So in immediate terms, we could go back to just skipping
> firewall/NAT
> issues in running.html.
> <zooko> For some people, it will happen to work without that.
> <warner> anyways, does my "first step" instructions above seem like the
> right
> level of detail for your immediate goals?
> <warner> and for you as a member of the first sort of audience?
> [13:03]
> <zooko> Here's another patch to running.html that I would like to at
> least
> partially revert:
> http://tahoe-lafs.org/trac/tahoe-
> lafs/changeset/4177/docs/running.html
> <zooko> David-Sarah added an alternative. I hate alternatives.
> <zooko> (In intro docs)
> [13:04]
> <glyph> warner: roughly, ye
> [13:05]
> <glyph> s
> <warner> actually the second step is: "now that the introducer is
> running,
> copy WORKDIR/introducer/introducer.furl , because you'll need it
> again later"
> <glyph> zooko: alternatives are okay, but only if there is a clear
> reason,
> like "If that didn't work..." or "If you see this error..."
> <warner> and the third step is ".../tahoe create-node --nickname 'my
> first
> storage server' --introducer 'PASTEINYOURintroducer.furlHERE'
> WORKDIR/storage"
> <glyph> zooko: IMHO the worst thing about the introductory document is
> the
> part where it explains that there are 3 UIs but doesn't say how
> to use
> them, or in FUSE's case, even how to build or run it
> [13:08]
> <warner> (note, this simple form of the instructions assumes that you'll
> be
> running your personal client on a different machine than the
> storage
> server, because the default 'tahoe create-node' claims port 3456
> for
> it's HTTP status interface. If you're testing on the same
> machine,
> you may want to create the storage server node with
> --webport=none to
> turn this off, leaving the port available for your client)
> <glyph> (And I _really_ don't care how you pronounce "wooey")
> <warner> yeah, that document shouldn't mention FUSE at all
> [13:09]
> <glyph> it should have several screenshots of doing things with the WUI,
> uploading a file, getting the capability for the file, copying
> it,
> pasting it into Pidgin, copying it out of Pidgin, pasting it
> wherever
> it goes, etc
> <glyph> and then a footnote at the bottom, "If you are adventurous and
> would
> like to help us build a more integrated user experience, there is
> some
> experimental FUSE code for mounting your Tahoe node in your
> operating
> system's filesystem structure"
> <warner> then the fourth step is: now go back to your client machine,
> pick a
> working directory, and do ".../tahoe create-client -n 'pick a
> nickname' -i 'PASTEINYOURintroducer.furlHERE' WORKDIR", and then
> ".../tahoe start WORKDIR"
> <glyph> warner: okay not bad, but "pick a nickname" is wrong. alice,
> bob.
> explain that you're picking nicknames and which one is going to
> be
> which, don't make me think :)
> [13:11]
> <glyph> or maybe mix it up a little: yolanda, xavier, zack
> <ducki2p> or just generate a random one and not bother the user with it
> <warner> glyph: ok, maybe "-n 'type your name here'"
> <glyph> warner: I'm serious, I think you should use 'alice' or something,
> and
> just say 'you can replace alice with your own name if you like'
> somewhere
> <warner> I think the fourth step is "tahoe create-alias tahoe" and "tahoe
> webopen tahoe:", but I'm currently trying to build tahoe on my
> work
> machine to test if that creates ~/.tahoe for you automatically
> or not
> <warner> glyph: maybe "let's pretend you call your storage machine Alice,
> and
> your client machine Bob.. then you'll pass -n options like so..,
> and
> you'll see the following things on your status displays:"
> <glyph> warner: that sounds great
> <glyph> warner: I especially like "you'll see the following things"
> <glyph> that gives me a very concrete indication that I haven't screwed
> up
> (yet) :)
> [13:16]
New description:
Glyph offered a lot of detailed criticism of "the introductory docs" --
install.html, running.html, and using.html.
My general take-away from this is:
1. Let the introductory docs first show how to share a file using a live
test grid.
2. Then, say why you might want to run your own gateway (confidentiality,
integrity), and how to acquire and build Tahoe-LAFS software and run a
gateway.
3. Then, say why you might want to run your own storage servers
(availability, reliability, provisioning), and how to run an introducer
and storage servers.
* Along the way you assiduously avoid saying anything that is not
necessary to the motivational and instructional bits. No terminology, no
explanations. Just why and how.
* Likewise, carefully eliminate all mention of alternatives: alternative
UIs that are not the WUI, "tahoe run" vs "tahoe start", different ways to
install if "install.html" doesn't work -- all of these get segregated off
to another document which people might eventually find if the basic
quickstart doesn't work for them.
* Likewise, no mention of optional features which are not necessary to do
the basic filesharing use case, such a providing a nickname for your
nodes.
* Along the way we need to provide "breadcrumbs" which give the user
confidence that they are still on the right track. Glyph suggests
screenshots. Sounds like a good idea!
* After the howto is finished you can point to another introductory doc
which is the "what" -- a simple summary of Tahoe-LAFS components and
behavior. There are some users, like Glyph and my brother Josh, who really
hate having that stuff mixed into their "why and how" howto, but there are
other users who refuse to follow the why-and-how howto until they've
learned the what-it-is overview. We need to address both types of reader.
By the way: I'm concerned about InstallDetails. It seems that some users
move from install.html to InstallDetails and then have troubles which they
would not have if they followed install.html. I've already put a note in
install.html claiming (more or less justifiably) that install.html works
on Windows, Mac, Linux, etc. I think we should also put a note at the top
of InstallDetails urging people to try install.html first and not to look
at InstallDetails unless install.html doesn't work for them. (And to
report a bug if that is the case.)
An open issue in my mind is what to do about the firewall/NAT issue. We
used to not-mention it in running.html, but enough people had problems
with it that we added a paragraph about it to running.html. However, every
sentence added to running.html hurts. Brevity is paramount. I think I'll
move those instructions to a different wiki page (not InstallDetails
because I'm trying to steer people away from InstallDetails) and put one
sentence in using.html that says "If the welcome page shows that some of
your servers are not connected to your gateway, like this [SCREENSHOT],
then perhaps you have a problem with firewalls or NAT -- see
FirewallsAndNat for how to fix that."
Excerpts from IRC:
{{{
<glyph> zooko: to be fair, Tahoe *is* a pain in the ass to use, it's just
not
a pain in the ass to use because of the encryption :)
<zooko> glyph: touché
[12:35]
<zooko> glyph: now tell me something more specific!
<glyph> zooko: the number of terms I have to learn about in order to even
_try_ to set it up is way too much cognitive laod
<zooko> glyph: Aha! Very useful feedback. Thanks! Hm.
[12:36]
...
<glyph> zooko: but it's not like I can read install.html and go; all
install.html gets me is a terminal window spewing some logs
<glyph> I have to read
http://allmydata.org/source/tahoe-lafs/trunk/docs/install.html and
http://allmydata.org/source/tahoe-lafs/trunk/docs/running.html and
http://allmydata.org/source/tahoe-lafs/trunk/docs/using.html
<zooko> glyph: so, your objection sounds very plausible to me -- I
wouldn't be
surprised if our docs inadvertently mention too many neutron flux
capacitors.
<zooko> But that particular set of three that you just posted are the one
that
are intended *not* to have.
<zooko> So I'm wondering if it is actually those ones that give you that
cognitive overload, or other ones.
[12:40]
<zooko> glyph: it was my idea to split that into three web pages. Perhaps
I
suck at web design.
<glyph> zooko: there are also no pictures on those pages
<glyph> zooko: have you ever read cyli's tutorial on
Twisted+Divmod/Windows
development? :)
[12:42]
<zooko> glyph: huh? What do you want, screenshots? Or network diagrams
like
http://secorp.net/images/network-and-reliance-topology.png
<zooko> glyph: I think I looked at it a while back. I'll look it up.
<zooko> You're recommending it as a good example of a tutorial?
<glyph> zooko: screenshots. I want confirmation that I have followed the
steps correctly and that what I'm seeing on my screen is an
indication
of success.
<glyph> If you can do that without screenshots, that's okay too
<zooko> glyph: hm. Okay, we can add a screenshot of the WUI to
http://allmydata.org/source/tahoe-lafs/trunk/docs/using.html
<zooko> glyph: is the part about "clients, servers, and introducers" on
http://allmydata.org/source/tahoe-lafs/trunk/docs/running.html
part
where you tend to fall off of the text?
<glyph> zooko: also, I want a tutorial that goes deeper
<zooko> That's the part that we could optimize out if someone else was
already
running a server grid for you...
<glyph> zooko: yes. The term "introducer", in particular, is unclear
<zooko> glyph: ok
<glyph> zooko: I *sort* of understand its purpose, but to a naive user it
really sounds like some extraneous piece of junk which you really
don't need
<glyph> zooko: let me get to my main point though
<glyph> (although the presence of the string "tub" without any explanation
of
what a "tub" is doesn't help either)
<zooko> Thanks for that note, too. I'll put all of this in the ticket.
<glyph> the real problem is that I don't really give a crap about anything
that this documentation is showing me how to do
<glyph> I already know how to create folders
<glyph> File->New Folder in Finder
[12:47]
<glyph> done
<glyph> I didn't need to "construct a client node" or "construct an
introducer"
<glyph> in order to do that
<glyph> what I really want the setup documentation to take me through is
the
simplest, fastest possible path to share a file with someone else
<zooko> Ah!
<glyph> I want to learn how to share files with tahoe
<glyph> I am actively un-interested in constructing an introducer tub node
flux capacitor
<glyph> so the setup documentation should take me through how to do it,
and it
should take me how to do it ONE way
<warner> glyph: go to http://testgrid.allmydata.org:3567/
<warner> upload a file into the "Upload a file" box
[12:49]
<zooko> So, there's a big difference between using someone else's pre-
existing
servers and setting up your own.
<zooko> Maybe the introductory docs could show you that -- the way to
share a
file using testgrid.allmydata.org --
<zooko> and then have a subsequent section explaining how to set up your
own
grid.
<warner> then copy the resulting "Download link:" URL and give it to the
person you want to get the file
<secorp> Here's a files for example:
<glyph> okay. maybe I want to set up my own. Do I? I don't know! What
does
setting up my own get me? I'm pretty sure that when I upload my
ssh
key to that form, warner will steal it and use it to get hot
insider
stock tipzzzz
<secorp>
http://testgrid.allmydata.org:3567/file/URI:CHK:azzp7eyzixkstgxd2ppejm3smu:laz6zt6fdg24fs3agoezhgahqoyi6pcwzd2grakl7orbzlxjpydq:3:10:252/@@named=/notice.txt
<glyph> so I want to run some secure software on my computer
[12:50]
<secorp> Sorry, "a file"
<idnar> is testgrid.allmydata.org as reliable as, say, dropbox.com though?
<zooko> idnar: ha
<idnar> or does that matter?
<zooko> idnar: for the purpose of introductory doc, we'll point at some
demo
grid.
<idnar> (I haven't read any Tahoe-LAFS documentation whatsoever, just
lurked
in the channel)
<zooko> So that Glyph can try sharing a file and, seeing that it worked,
go
ahead and read the next page of the doc.
[12:51]
<zooko> Even though the demo grid is unreliable and warner reads all the
confidential files shared thereby.
<glyph> warner: right, so that's not very interesting to me
<zooko> But then the next paragraph of the doc explains why you might want
to
run your own instead of using that one.
<glyph> I want to securely share some files on a private network with my
friends
<zooko> glyph: right, and that's where the current install.html starts.
<glyph> zooko: okay. So, install.html isn't too bad. It leaves out the
part
where I have to fight with setuptools for two hours because it
wanted
to corrupt my /Library/Frameworks/Python.framework directory, but
arguably that's my own fault.
<glyph> zooko: the problems start in running.html
<glyph> in fact I think the problems start in the first sentence
<zooko> glyph: no you are wrong!
<zooko> install.html never told you to install anything into your system
folders.
<glyph> "This is how to run a Tahoe client *OR* a complete Tahoe grid"
* zooko double-checks...
<warner> I wonder if the verbs we use to name those documents are
misleading..
[12:54]
<zooko> Yes. There is no "installing".
<zooko> Ah good point.
<zooko> There is no "installing" in "install.html".
<glyph> Perhaps tahoe wanted to break my system because of InstallDetails
<glyph> it's been a while since I actually did this
<warner> tahoe runs fine out of the source tree
[12:55]
<glyph> but running.html is trying to tell me too much stuff
<warner> ./bin/tahoe $command
<zooko> Yes, I have mixed feelings about InstallDetails.
<zooko> It seems people frequently skip install.html for one reason or
another,
<zooko> go to InstallDetails, and then have all sorts of problems.
<zooko> Anyway, what were you saying about the worst problems being in
running.html
* zooko looks at running.html
[12:56]
<glyph> I really don't care about creating, stopping and starting nodes; I
don't care what a tahoe network is made of. I am looking for a
very
linear set of instructions telling me how to get one particular
thing
done.
<warner> glyph: does "./bin/tahoe --version" work for you?
<glyph> warner: Yes.
<zooko> Yes, running.html has grown.
<warner> great, that's most of the battle won
<zooko> Communally edited docs tend to grow more than to shrink...
<zooko> glyph: specifically, I originally wrote running.html more along
the
lines of what you are asking for.
[12:57]
<glyph> What I really want (especially with my "very impatient but
slightly
curious user" hat on) is something that says "do this. then do
that.
then do this other thing. Now you can securely share files with
your
friends, if they do this, and then do that!"
<zooko> And then others came along and said "Hey this doesn't have enough
explanation" and added some details.
<zooko> So I think after I copy some of your comments to a trac ticket
I'll go
prune it back again...
<warner> glyph: first step, choose a machine that all of your potential
clients can access, and make sure that "./bin/tahoe --version"
works
on it, and pick a working directory, and run
".../path/to/bin/tahoe
create-introducer WORKDIR/introducer" and also ".../tahoe start
WORKDIR/introducer"
<glyph> then at the _end_ of the document, or _after_ the steps where I do
stuff that gets something set up, you can tell me "You just set up
an
introducer node. The purpose of this thing is to ..."
<warner> then you need at least one storage server, which can be on the
same
machine as the introducer
[12:58]
<glyph> "getting everybody talking to each other" is simultaneously too
much
detail (why do I care what this thing does? I just want to share
a
file!) and not enough (isn't "getting everybody talking to each
other"
what like, sockets, and ethernet cables, are for?)
<warner> second step: same as above, but use "create-node WORKDIR/storage"
and
"start WORKDIR/storage"
[12:59]
<warner> glyph: ah, so now the instructions that you want have bifurcated
<glyph> warner: I want to read about all of these things, but I want to
read
about the conceptual explanation _after_ I've got something
working
with my friends
[13:00]
<warner> there is one audience, like you, who is well aware of just how
annoying the modern internet is, and how it's NP-Hard to get one
computer to send a message to another
<glyph> similarly, I don't really care about multiple UIs; it should
really
just show me the best one (which, sadly, really ought to be the
FUSE
one)
<warner> to whom "make sure your server has a publically-routable IP
address"
makes sense, even if the need to say that makes them cry
<zooko> I think this is the worst patch to running.html:
http://tahoe-lafs.org/trac/tahoe-
lafs/changeset/4044/docs/running.html
[13:01]
<glyph> warner: okay so, step 1, include vertex in foolscap and do NAT
punching so you don't need any of that config nonsense ;)
<warner> the other audience doesn't want to know about this pain, and
wants to
believe that the little radar-shaped wifi icon means they can see
the
whole world
<zooko> A user, Sam Mason, had trouble with running.html and submitted a
diff
adding all these details.
<zooko> glyph: the FUSE one doesn't work. The one default ui will be the
WUI
for the next release or so.
<glyph> Seriously though, the important thing is just to say "do this,
then do
that", and if I'm a smarty pants who thinks that I know better
what
port number my firewall should be pointing at Tahoe I can change
it,
but I probably don't
[13:02]
<warner> glyph: you know full well that won't be enough: which QSP do you
sign
up with? how do you get an account with them? what's a QSP
anyway?
making it at least step -3 or so :)
<glyph> warner: yes yes, it was a joke :)
<warner> yeah, I know :)
<zooko> So in immediate terms, we could go back to just skipping
firewall/NAT
issues in running.html.
<zooko> For some people, it will happen to work without that.
<warner> anyways, does my "first step" instructions above seem like the
right
level of detail for your immediate goals?
<warner> and for you as a member of the first sort of audience?
[13:03]
<zooko> Here's another patch to running.html that I would like to at least
partially revert:
http://tahoe-lafs.org/trac/tahoe-
lafs/changeset/4177/docs/running.html
<zooko> David-Sarah added an alternative. I hate alternatives.
<zooko> (In intro docs)
[13:04]
<glyph> warner: roughly, ye
[13:05]
<glyph> s
<warner> actually the second step is: "now that the introducer is running,
copy WORKDIR/introducer/introducer.furl , because you'll need it
again later"
<glyph> zooko: alternatives are okay, but only if there is a clear reason,
like "If that didn't work..." or "If you see this error..."
<warner> and the third step is ".../tahoe create-node --nickname 'my first
storage server' --introducer 'PASTEINYOURintroducer.furlHERE'
WORKDIR/storage"
<glyph> zooko: IMHO the worst thing about the introductory document is the
part where it explains that there are 3 UIs but doesn't say how to
use
them, or in FUSE's case, even how to build or run it
[13:08]
<warner> (note, this simple form of the instructions assumes that you'll
be
running your personal client on a different machine than the
storage
server, because the default 'tahoe create-node' claims port 3456
for
it's HTTP status interface. If you're testing on the same
machine,
you may want to create the storage server node with
--webport=none to
turn this off, leaving the port available for your client)
<glyph> (And I _really_ don't care how you pronounce "wooey")
<warner> yeah, that document shouldn't mention FUSE at all
[13:09]
<glyph> it should have several screenshots of doing things with the WUI,
uploading a file, getting the capability for the file, copying it,
pasting it into Pidgin, copying it out of Pidgin, pasting it
wherever
it goes, etc
<glyph> and then a footnote at the bottom, "If you are adventurous and
would
like to help us build a more integrated user experience, there is
some
experimental FUSE code for mounting your Tahoe node in your
operating
system's filesystem structure"
<warner> then the fourth step is: now go back to your client machine, pick
a
working directory, and do ".../tahoe create-client -n 'pick a
nickname' -i 'PASTEINYOURintroducer.furlHERE' WORKDIR", and then
".../tahoe start WORKDIR"
<glyph> warner: okay not bad, but "pick a nickname" is wrong. alice, bob.
explain that you're picking nicknames and which one is going to be
which, don't make me think :)
[13:11]
<glyph> or maybe mix it up a little: yolanda, xavier, zack
<ducki2p> or just generate a random one and not bother the user with it
<warner> glyph: ok, maybe "-n 'type your name here'"
<glyph> warner: I'm serious, I think you should use 'alice' or something,
and
just say 'you can replace alice with your own name if you like'
somewhere
<warner> I think the fourth step is "tahoe create-alias tahoe" and "tahoe
webopen tahoe:", but I'm currently trying to build tahoe on my
work
machine to test if that creates ~/.tahoe for you automatically or
not
<warner> glyph: maybe "let's pretend you call your storage machine Alice,
and
your client machine Bob.. then you'll pass -n options like so..,
and
you'll see the following things on your status displays:"
<glyph> warner: that sounds great
<glyph> warner: I especially like "you'll see the following things"
<glyph> that gives me a very concrete indication that I haven't screwed up
(yet) :)
[13:16]
--
Comment (by zooko):
#1882 is a duplicate of this ticket that includes useful information.
Please read it!
--
Ticket URL: <https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1024#comment:29>
tahoe-lafs <https://tahoe-lafs.org>
secure decentralized storage
More information about the tahoe-lafs-trac-stream
mailing list