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

New Issue

warner · 2016-05-06T17:03:38Z

warner commented

2016-05-06 17:03:38 +00:00

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!

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!