#1701 closed enhancement (fixed)

remove link to wiki:AdvancedInstall from quickstart.rst

Reported by: zooko Owned by: zooko
Priority: normal Milestone: 1.9.2
Component: documentation Version: 1.9.1
Keywords: docs quickstart reviewed Cc:
Launchpad Bug:

Description

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.

Attachments (1)

remove-link-to-AdvancedInstall.diff.patch (1.0 KB) - added by zooko at 2012-03-31T04:35:01Z.

Download all attachments as: .zip

Change History (6)

comment:1 Changed at 2012-03-31T04:36:28Z by zooko

  • Keywords review-needed added

Please review!

comment:2 Changed at 2012-03-31T16:43:33Z by davidsarah

  • Keywords docs quickstart added; review-needed removed
  • Milestone changed from undecided to 1.9.2
  • Owner changed from somebody to zooko

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>`_. 

comment:3 follow-up: Changed at 2012-03-31T16:51:37Z by zooko

  • Keywords review-needed added
  • Owner changed from zooko to davidsarah

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?

comment:4 in reply to: ↑ 3 Changed at 2012-03-31T18:54:41Z by davidsarah

  • Keywords reviewed added; review-needed removed
  • Owner changed from davidsarah to zooko

Replying to zooko:

Good enough?

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

comment:5 Changed at 2012-04-01T02:10:01Z by zooko@…

  • Resolution set to fixed
  • Status changed from new to closed

In 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)
Note: See TracTickets for help on using tickets.