tahoe-lafs/trac-2024-07-25

remove link to wiki:AdvancedInstall from quickstart.rst #1701

New issue

Closed

opened 2012-03-31 04:34:13 +00:00 by zooko · 6 comments

zooko commented

2012-03-31 04:34:13 +00:00

Owner

John Dougherty was just trying to install tahoe-lafs. He asked me for help, saying something like "I'm failing at installing Twisted". I said something like "whoa whoa whoa -- who told you to install Twisted?". (Because my preference is that Twisted gets installed automatically, if needed, by the build process.) He showed me how he was following wiki/AdvancedInstall and going through the list of dependencies trying to manually install them. I said something like "Aurgh! How did you get to this page?". He showed me that he had gotten to it by following the link at the end of source:docs/quickstart.rst . I said something like "I have made the text surrounding that link as forbidding as I can! It tells you not to follow the link. Why did you follow the link?". He said something like "Well I scanned this document for a list of dependencies to manually install, and I didn't see on, so I followed the link at the bottom named 'something Install something', and then I saw a list of dependencies to manually install.".

My conclusion is that the only way to keep people from wandering into wiki/AdvancedInstall and getting bogged down in the quicksand pits that we keep there is to remove the link to there from quickstart.rst.

John Dougherty was just trying to install tahoe-lafs. He asked me for help, saying something like "I'm failing at installing Twisted". I said something like "whoa whoa whoa -- who told you to install Twisted?". (Because my preference is that Twisted gets installed automatically, if needed, by the build process.) He showed me how he was following [wiki/AdvancedInstall](wiki/AdvancedInstall) and going through the list of dependencies trying to manually install them. I said something like "Aurgh! How did you get to this page?". He showed me that he had gotten to it by following the link at the end of source:docs/quickstart.rst . I said something like "I have made the text surrounding that link as forbidding as I can! It tells you not to follow the link. Why did you follow the link?". He said something like "Well I scanned this document for a list of dependencies to manually install, and I didn't see on, so I followed the link at the bottom named 'something Install something', and then I saw a list of dependencies to manually install.". My conclusion is that the only way to keep people from wandering into [wiki/AdvancedInstall](wiki/AdvancedInstall) and getting bogged down in the quicksand pits that we keep there is to remove the link to there from quickstart.rst.

tahoe-lafs added the

labels 2012-03-31 04:34:13 +00:00

tahoe-lafs added this to the undecided milestone 2012-03-31 04:34:13 +00:00

zooko commented

2012-03-31 04:35:01 +00:00

Author

Owner

Attachment remove-link-to-AdvancedInstall.diff.patch (1064 bytes) added

**Attachment** remove-link-to-AdvancedInstall.diff.patch (1064 bytes) added

remove-link-to-AdvancedInstall.diff.patch

1 KiB

zooko commented

2012-03-31 04:36:28 +00:00

Author

Owner

Please review!

davidsarah commented

2012-03-31 16:43:33 +00:00

Author

Owner

I recommend keeping something like:

If the instructions on this page don't work, ask for help by writing to
`the tahoe-dev mailing list <https://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev>`_.

I recommend keeping something like: ``` If the instructions on this page don't work, ask for help by writing to `the tahoe-dev mailing list <https://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev>`_. ```

tahoe-lafs modified the milestone from undecided to 1.9.2

2012-03-31 16:43:33 +00:00

zooko commented

2012-03-31 16:51:37 +00:00

Author

Owner

I agree. That way we can find out if people are getting stuck trying to use quickstart.rst and we need to extend it.

Oh, we already have this:

In Case Of Trouble
------------------

There are a few 3rd party libraries that Tahoe-LAFS depends on that might not
be easy to set up on your platform. If the following instructions don't Just
Work without any further effort on your part, then please write to `the tahoe-dev mailing list`_ where friendly hackers will help you out.

.. _the tahoe-dev mailing list: https://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev

Good enough?

I agree. That way we can find out if people are getting stuck trying to use `quickstart.rst` and we need to extend it. Oh, we already have this: ``` In Case Of Trouble ------------------ There are a few 3rd party libraries that Tahoe-LAFS depends on that might not be easy to set up on your platform. If the following instructions don't Just Work without any further effort on your part, then please write to `the tahoe-dev mailing list`_ where friendly hackers will help you out. .. _the tahoe-dev mailing list: https://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev ``` Good enough?

davidsarah commented

2012-03-31 18:54:41 +00:00

Author

Owner

Replying to zooko:

Good enough?

Yes. I didn't see that because I was only looking at the diff.

Replying to [zooko](/tahoe-lafs/trac-2024-07-25/issues/1701#issuecomment-129460): > Good enough? Yes. I didn't see that because I was only looking at the diff.

zooko@zooko.com commented

2012-04-01 02:10:01 +00:00

Author

Owner

In changeset:638dcf867aaf1eb2:

docs: quickstart: edits

• use out-of-line links to avoid a warning from rst2html --verbose (fixes #1704)
• reflow to 77 fill-column and prepend utf-8 BOM (fixes #1703)
• recommend Python 2.7 (fixes #1702)
• remove link to wiki:AdvancedInstall (fixes #1701)

In changeset:638dcf867aaf1eb2: ``` docs: quickstart: edits • use out-of-line links to avoid a warning from rst2html --verbose (fixes #1704) • reflow to 77 fill-column and prepend utf-8 BOM (fixes #1703) • recommend Python 2.7 (fixes #1702) • remove link to wiki:AdvancedInstall (fixes #1701) ```

tahoe-lafs added the

fixed

label 2012-04-01 02:10:01 +00:00

zooko@zooko.com closed this issue

2012-04-01 02:10:01 +00:00