docs concept: task / things-to-learn / things-to-do

[warner]

I had a thought about a new introductory document.

It would have four top-level sections, each about a particular task, titled "If you want to do X:".

Each section would have a "things you must learn" portion, and a "things you must do" portion. That way we could explain what concepts were necessary to perform a given task, and (perhaps more importantly) which concepts were *not* necessary for the task.

• "If you want to connect a client to an existing grid":
  • to learn: what is a grid (introducers+servers+clients), how to configure a client, what are files/writecaps/rootcaps/dirs/webapi
  • to do: install tahoe, "run tahoe create-client", configure introducer.furl, "tahoe start", open webapi, maybe make alias

• "If you want to add a server to an existing grid":
  • to learn: IP addresses, public-vs-private, firewall port-forwarding, stoage-server config (reserved space), maintenance tools
  • to do: "tahoe create-server", configure introducer.furl, start, monitor

• "If you want to create a new grid":
  • to learn: introducers
  • to do: "tahoe create-introducer", start, distribute introducer.furl, monitor

• "If you want to hack on Tahoe and contribute to development":
  • to learn: git, pip, virtualenv, tox, trac, patches, tickets, PRs, IRC, tahoe-dev mailing list
  • to do: git clone, virtualenv, activate, trial, tox

The earlier sections can reference single-file installers and "apt-get" packages. We don't need to explain pip or running from source until the hack-on-tahoe task.

Marlowe told me I should assign this to him.. thanks!

[dawuud]

There's a related ticket regarding server-side network considerations here: ​https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2827