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]

[terrell]

Consider renaming InstallDetails to InstallOptions?

It could dissuade the early leapers from install.html as it does not suggest the 'real' way to do things, but rather, a few alternate ways of doing things.

[davidsarah]

The instructions in install.html are not sufficient on Windows, where you also need to install pywin32.

[zooko]

Hm, currently install.html says:

"(If installing on Windows, you now need to manually install the pywin32 package -- see "More Details" below.)"

"More Details" below says:

"For more details, including platform-specific hints for Debian, Windows, and Mac systems, please see the InstallDetails wiki page. If you are running on Windows, you need to manually install "pywin32", as described on that page."

InstallDetails says:

"In addition to these, if you are installing on Microsoft Windows, then you need to manually install pywin32 before installing Tahoe-LAFS."

and later it says

"2. Download and install pywin32 from ​http://sourceforge.net/projects/pywin32/files/pywin32/Build%20214/pywin32-214.win32-py2.6.exe/download."

and then

"If you prefer to use Python 2.5, you must install a 2.5 build of pywin32 and also install OpenSSL or Tahoe-LAFS will fail to run with an error about being unable to find ssl.dll."

That last is probably somewhat confused -- if you don't have a Python 2.5 build of pywin32 this will probably not result in an error about being unable to find ssl.dll.

But anyway, we don't need to explain that part on install.html, so the only detail that InstallDetails seems to add is the URL which is for a specific version of Python (2.6), a specific version of pywin32 (build 214) and anyway doesn't seem all that important to include since "pywin32" is easy to find with a search engine. If we do what to include a URL, then we should probably just change install.html to say:

"(If installing on Windows, you now need to manually install the pywin32 package from ​the pywin32 site.)"

By the way, the only reason we have to mention pywin32 explicitly, out of all fifteen (!) Python package dependencies, is because pywin32 can't be automatically installed by setuptools. I'm investigating if this is still the case in distribute (the successor to setuptools).

[zooko]

That pywin32 can't be installed by setuptools/distribute is issue #142.

[davidsarah]

Replying to zooko:

Hm, currently install.html says:

"(If installing on Windows, you now need to manually install the pywin32 package -- see "More Details" below.)"

[...]

... we should probably just change install.html to say:

"(If installing on Windows, you now need to manually install the pywin32 package from ​the pywin32 site.)"

Sounds good to me.

[davidsarah]

s/you now need/you first need/

[zooko]

I made some changes to the start docs:

​http://tahoe-lafs.org/trac/tahoe-lafs/wiki/AdvancedInstall?action=diff&version=2 ​http://tahoe-lafs.org/trac/tahoe-lafs/wiki/AdvancedInstall?action=diff&version=3 ​http://tahoe-lafs.org/trac/tahoe-lafs/wiki/InstallDetails?action=diff&version=24http://tahoe-lafs.org/trac/tahoe-lafs/changeset/4269

[zooko]

There are broken links to images on about.html.

running.html seems like the worst part of the introductory docs as far as telling you about flux capacitors (it starts by defining three different types of "nodes")...

[davidsarah]

Replying to zooko:

running.html seems like the worst part of the introductory docs as far as telling you about flux capacitors (it starts by defining three different types of "nodes")...

e8636ee4bec52af4 simplifies that.

I also think that the section on firewalls and NATs should be removed from running.html. You really need to read source:docs/configuration.txt anyway to see how and whether to set tub.location.

[davidsarah]

Remove firewall section from running.html and say to read configuration.txt instead.

[davidsarah]

This patch merges using.html into running.html, replaces the FUSE section with a section on SFTP and FTP, and changes the 'Socialize' section to reference the #tahoe IRC channel and tahoe-dev list. It is dependent on the previous patch.

[kevan]

#tahoe should be #tahoe-lafs, I think.

There are several instances of Tahoe in what was using.html that should be changed to Tahoe-LAFS for consistency with the text that was already in running.html.

Looks good otherwise.

[davidsarah]

Applied in 1c7e71ee52caaf00, 965f0dcfc32343ec, 6d669029bdf29136, 8784e4a596cccf87 (which addresses kevan's comments).

[zooko]

Glyph has intoned the following words of wisdom:

close! But there are two jargon terms in the first sentence :)

[zooko]

Hm, I actually don't know what he means, but here are words that I think are jargony: the PubGrid...

And, um, maybe pubgrid is updated -- perhaps people don't know what that means, and anyway I guess it is sufficient to say something like "It isn't intended to be reliable.".

As for "is not a free backup service", let's say something like "It isn't intended to be used for backup — files stored on the pubgrid are not guaranteed to remain there forever."

Maybe call it "the public demo grid" instead of "the pubgrid".

[marlowe]

Updated description of pubgrid and hopefully removed all jargony terms.

[zooko]

This is being reviewed my marlowe's wife.

[zooko]

Reassigning this ticket from "marlowe's wife" to marlowe. It would be great to have the introductory docs all polished up in time for the 1.9 release. That way all the new users who will try it out when they hear about 1.9 will get a better start.

[zooko]

I was just searching the internet for mention of Tahoe-LAFS and I found this discussion on a bulletin board where apparently this windows user was scared off by the fact that quickstart.rst appeared to be instructing them to type things into their computer!

​http://forum.i2p2.de/viewtopic.php?p=32165#32165

I'm not sure what we can do about this, except possibly to add text to quickstart.rst reassuring Windows users that this is actually not a Linux-only thing even though it involves typing words and maybe even explaining, as the responder did on that forum, how to open cmd.exe.

[zooko]

There was a discussion of distributed data stores and of Tahoe-LAFS on the p2p-hackers mailing list, and I asked people there to give us feedback on the quickstart. Serguei Osokine posted ​this reply:

On Thursday, September 01, 2011 Zooko O'Whielacronx wrote:

You would be more than welcome to jump in and help. Try following the "quick start" instructions [2] and tell us how it works for you.

Okay, let's see:

"Check if you already have an adequate version of Python installed...

Unpack the zip file and cd into the top-level directory...

Run python setup.py build...

On Windows, the build step might tell you to open a new Command Prompt..

If the Tahoe-LAFS bin directory is not on your PATH, then in all the command lines below, specify the full path to bin/tahoe...

To construct a client node, run "tahoe create-client", which will create ~/.tahoe to be the node's base directory. Acquire the introducer.furl (see below if you are running your own introducer, or use the one from the TestGrid page), and paste it after introducer.furl = in the [client] section of ~/.tahoe/tahoe.cfg. Then use "tahoe run ~/.tahoe". After that, the node should be off and running...

By default, "tahoe create-client" creates a client-only node, that does not offer its disk space to other nodes. To configure other behavior, use "tahoe create-node"...

To construct an introducer, create a new base directory for it (the name of the directory is up to you), cd into it, and run "tahoe create-introducer .". Now run the introducer using "tahoe start ."."

Zooko, man... I love what you're doing, but you gotta be kidding. You want to use it with a few friends, or you want normal people to use it, too? This whole web site should say just this:

"Run _setup.exe_. Use the drive Z: that will appear on your machine."

The way it looks to me, only after you get installation down to this procedure (or something of comparable complexity - say, 19 words or less - you can start asking any other questions about why people are not using globally distributed P2P data archive. Of course, this stuff won't be sufficient for success - but it seems to be a necessary condition for one.

Best wishes - S.Osokine. 2 Sep 2011.

[davidsarah]

Replying to zooko:

"Run _setup.exe_. Use the drive Z: that will appear on your machine."

This is what people think they want, but I'm really not sure that if we gave them it they would be happy. The setup.exe part maybe (most of the work to support that was done in #585) -- but wanting to just use a drive letter, especially on Windows, is not taking into account all the broken performance and semantic assumptions that apps make about filesystems that look local actually being local.

[zooko]

From the #cryptodotis channel:

<tokx> im not sure i understand this, if one uses tahoe-lafs, files are stored on random tahoe-lafs servers? who owns the servers?

<AmmonRa3543533> I'm not sure, but from reading the intro page, i get the idea that it would depend on how you set it up. you could setup 10 of your own servers, or form a group with some friends who each owns one server, or you could pay for SaaS

[zooko]

marlowe: would you please review attachment:update-doc-about.rst.darcs.patch​ ? Just read it and post here if there are any errors added. :-)

[marlowe]

Reviewed the patch, looks good to me.

[warner]

It looks like everything (formatting changes, minor wording change about mutable files) in attachment:update-doc-about.rst.darcs.patch​ is already in trunk, except for the em-dash change. I don't personally care for the em-dash (without having spaces on either side, it reads badly in the original plain-text, although I imagine an HTML rendering might do better), so I'm happy to leave that out. So I consider that patch landed and done.

Is there anything left to this ticket?

[zooko]

Agreed that attachment:update-doc-about.rst.darcs.patch​​ was committed in 4a29642623196b4b ≈ [20111206171908-92b7f-1c2623b8ac7dd9afb339a4f9f90d4b76088fbf1b/trunk].

However, the ticket is far from fixed. The introductory docs are (I suspect) still confusing and off-putting to newcomers. The suggestions by Glyph, Serguei Osokine, Brian Warner, and others that have been noted in the comments on this ticket still deserve more work.

Is there a way that we can break this ticket into smaller tickets or otherwise define a smaller unit of work on which we can make definite progress?

How about: take the current introductory docs as they now exist, find an innocent, untainted user who has never tried to use Tahoe-LAFS before, and watch carefully while they try to figure it out, and take notes. That could be a separate ticket which someone could complete in a finite amount of work.

[zooko]

#1882 is a duplicate of this ticket that includes useful information. Please read it!