Improve documentation

[richardxia]

We should improve the documentation of wit. Here are some rough ideas of things to improve:

Tutorial

• [ ] Perhaps better define what a "workspace" is. The tutorial introduces it as a term, but doesn't define it, other than saying that wit init will create one. We don't need to get too detailed, but I think it's a central-enough concept in Wit that deserves a more detailed explanation in the tutorial.
• [ ] Closer to the top of the tutorial, perhaps state what the you will accomplish by going through the tutorial. I imagine a new user may not exactly where we are going, and describing the end state may help motivate the intermediate steps. I'm thinking something to the effect of "In this tutorial, you will create a Wit workspace with a package that depends on another package, and by the end you will have bumped the versions of both packages".
• [ ] Scrap extraneous information/explanations.
  • For example the following sentence and code example is not really essential to explain in the tutorial:

    Note that the above is equivalent to cloning a repository into the workspace and then adding it by directory

  • [ ] Explaining git -C or wit -C may not be necessary. (I don't personally make use of either in my normal workflow, since I usually just cd into the directory I want to work in.)
• [ ] Some of the non-essential content could possibly be moved into an advanced-level tutorial

How-to guides

• [x] Most of the content in the README's "Getting Started" section could be moved to a list of how-to guides/cookbooks
• In addition, we should add:
  • [ ] How to add a dependency to a package
  • [ ] How to update a dependency in a package
  • [x] How to print the dependency tree

Explanation

• [ ] The distinction between a workspace and a package in greater detail
• [ ] The wit-manifest.json, wit-workspace.json, and wit-lock.json files
• [ ] The dependency resolution algorithm

Reference

Perhaps just a document that can be automatically generated from argparse objects? Also, we could probably improve the existing help text.

[richardxia]

@jackkoenig, @mmjconolly, I've turned the above into a set of checklists, and I'm thinking of starting to work on these things. I think we can keep the ticket description above as a living document/tracking list of documentation, so feel free to make suggestions here or directly edit it.

I'm going to immediately start working on the "How to print the dependency tree" item.