[tahoe-dev] [tahoe-lafs] #1024: introductory docs are confusing and off-putting
tahoe-lafs
trac at allmydata.org
Wed Apr 14 15:11:06 PDT 2010
#1024: introductory docs are confusing and off-putting
--------------------------------------------+-------------------------------
Reporter: zooko | Owner: nobody
Type: defect | Status: new
Priority: major | Milestone: 1.7.0
Component: unknown | Version: 1.6.1
Keywords: docs install packaging website | Launchpad_bug:
--------------------------------------------+-------------------------------
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]
--
Ticket URL: <http://allmydata.org/trac/tahoe/ticket/1024>
tahoe-lafs <http://allmydata.org>
secure decentralized file storage grid
More information about the tahoe-dev
mailing list