introductory docs are confusing and off-putting

[zooko]

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]