Opened at 2010-04-14T22:11:06Z
Last modified at 2024-08-27T15:58:40Z
#1024 new defect
introductory docs are confusing and off-putting
Reported by: | zooko | Owned by: | blaisep |
---|---|---|---|
Priority: | major | Milestone: | User Documentation Goals |
Component: | documentation | Version: | 1.6.1 |
Keywords: | docs install packaging website tahoe-run | Cc: | glyph@… |
Launchpad Bug: |
Description (last modified by 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:
- Let the introductory docs first show how to share a file using a live test grid.
- 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.
- 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]
Attachments (4)
Change History (40)
comment:1 Changed at 2010-04-14T23:50:05Z by terrell
comment:2 Changed at 2010-04-15T02:16:17Z by davidsarah
The instructions in install.html are not sufficient on Windows, where you also need to install pywin32.
comment:3 follow-up: ↓ 5 Changed at 2010-04-15T03:27:59Z by 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).
comment:4 Changed at 2010-04-15T04:21:44Z by zooko
That pywin32 can't be installed by setuptools/distribute is issue #142.
comment:5 in reply to: ↑ 3 Changed at 2010-04-15T18:02:32Z by 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.
comment:6 Changed at 2010-04-15T18:03:28Z by davidsarah
s/you now need/you first need/
comment:7 Changed at 2010-04-21T17:06:17Z by 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
comment:8 follow-up: ↓ 9 Changed at 2010-06-08T06:57:28Z by 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")...
comment:9 in reply to: ↑ 8 Changed at 2010-06-17T00:55:23Z by 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.
Changed at 2010-06-17T00:58:20Z by davidsarah
Remove firewall section from running.html and say to read configuration.txt instead.
comment:10 Changed at 2010-06-17T00:59:33Z by davidsarah
- Keywords review-needed added
Changed at 2010-06-17T01:45:16Z by 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.
comment:11 Changed at 2010-06-19T00:35:47Z by 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.
comment:12 Changed at 2010-06-19T03:45:05Z by davidsarah
- Milestone changed from 1.7.0 to 1.7.1
Applied in 1c7e71ee52caaf00, 965f0dcfc32343ec, 6d669029bdf29136, 8784e4a596cccf87 (which addresses kevan's comments).
comment:13 Changed at 2010-06-19T05:30:04Z by davidsarah
- Component changed from unknown to documentation
- Keywords review-needed removed
- Owner changed from nobody to somebody
comment:14 Changed at 2010-07-18T02:34:55Z by davidsarah
- Milestone changed from 1.7.1 to soon
comment:15 Changed at 2010-07-21T16:45:28Z by zooko
- Keywords tahoe-run added
comment:16 Changed at 2011-05-08T02:35:33Z by zooko
Glyph has intoned the following words of wisdom:
close! But there are two jargon terms in the first sentence :)
comment:17 Changed at 2011-05-08T02:39:57Z by 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".
Changed at 2011-05-09T13:47:13Z by marlowe
Updated description of pubgrid and hopefully removed all jargony terms.
comment:18 Changed at 2011-05-19T16:42:51Z by zooko
- Keywords review-needed added
This is being reviewed my marlowe's wife.
comment:19 Changed at 2011-06-01T11:50:05Z by zooko
- Owner changed from somebody to marlowe's wife
comment:20 Changed at 2011-08-18T22:45:29Z by zooko
- Owner changed from marlowe's wife to marlowe
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.
comment:21 Changed at 2011-08-19T17:14:15Z by 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.
comment:22 follow-up: ↓ 23 Changed at 2011-09-03T04:18:54Z by 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.
comment:23 in reply to: ↑ 22 Changed at 2011-09-04T05:25:11Z by 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.
comment:24 Changed at 2011-09-14T06:21:31Z by 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
Changed at 2011-12-06T19:05:37Z by zooko
comment:25 Changed at 2011-12-06T19:06:46Z by 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. :-)
comment:26 Changed at 2011-12-06T22:42:09Z by marlowe
Reviewed the patch, looks good to me.
comment:27 Changed at 2012-05-13T02:49:04Z by warner
- Keywords review-needed removed
- Owner changed from marlowe to zooko
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?
comment:28 Changed at 2012-05-13T03:25:20Z by 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.
comment:29 Changed at 2013-09-26T17:11:35Z by zooko
- Description modified (diff)
#1882 is a duplicate of this ticket that includes useful information. Please read it!
comment:30 Changed at 2015-05-05T15:22:12Z by zooko
Here's another data point that the current running.rst is too complicated for people — even technical computer programmers — to wade through in order to launch the client:
https://twitter.com/sanjay/status/595602503275798528
I have some ideas about this.
First one is get a UX expert like Gus to brainstorm what the user experience should ideally be, starting from the install process.
My second idea is to look at running.rst and see what are the steps that it is instructing the user to do and not Wizardify those steps but remove those steps. We can in some cases remove the steps entirely so that the thing Just Works without that step, and in other cases we can move those steps from the basic introductory docs to advanced docs, because those steps are optional.
The first such step that we might be able to optimize out of running.rst is passing the introducer furl from the introducer to the client. This is potentially optimize-outable because of #403 grid identifiers. I think that basically means stuffing the introducer furl into the file/dir caps, but with some optimizations so it doesn't bloat the caps as much. Brian: what do you think? Could gridids optimize out one of the steps from running.rst?
The next such step is to set the default K, M, and H to 1 and remove mention of K, M, and H from the introductory doc. Running more than one server, or using erasure coding will be advanced features that people can level-up to after the understand the basic K=M=H=1 deployment. (This is ticket #1082 default servers-of-happiness=7 prevents single-server use case from working "out of the box".)
comment:31 Changed at 2021-03-31T13:14:06Z by maylee
- Owner changed from zooko to maylee
- Status changed from new to assigned
comment:32 Changed at 2021-03-31T13:20:28Z by maylee
- Milestone changed from soon to 2021 Documentation Goals
comment:33 Changed at 2021-05-02T13:00:57Z by maylee
- Milestone changed from 2021 Documentation Goals to User Documentation Goals
Milestone renamed
comment:34 Changed at 2021-06-09T16:59:35Z by maylee
- Owner changed from maylee to YashNRam
- Status changed from assigned to new
comment:35 Changed at 2021-06-09T17:01:35Z by maylee
Here's other documentation that has been written:
comment:36 Changed at 2024-08-27T15:58:40Z by blaisep
- Owner changed from YashNRam to blaisep
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.