Various documentation updates

Author: jeromekelleher

docs/installation.md

@@ -1,3 +1,4 @@
+(sec-installation)=
 # Installation
 
 
@@ -20,6 +21,12 @@ vcf2zarr <args>
 ```
 and will always work.
 
+:::{note}
+The ``python3 -m bio2zarr vcf2zarr`` for may be replaced with
+``python3 -m bio2zarr.vcf2zarr`` in the near future.
+See GitHub issue [203](https://github.com/sgkit-dev/bio2zarr/issues/203).
+:::
+
 
 :::{warning}
 Windows is not currently supported. Please comment on

docs/intro.md

@@ -23,3 +23,5 @@ support for other formats (or an interested in helping with implementing),
 please open an [issue on Github](https://github.com/sgkit-dev/bio2zarr/issues)
 to discuss!
 
+The package is currently focused on command line interfaces, but a
+Python API is also planned.

docs/vcf2zarr/cli_ref.md

@@ -1,3 +1,4 @@
+(sec-vcf2zarr-cli-ref)=
 # CLI Reference
 
 % A note on cross references... There's some weird long-standing problem with
@@ -57,6 +58,7 @@
 ## Encode
 
 ```{eval-rst}
+.. _cmd-vcf2zarr-encode:
 .. click:: bio2zarr.cli:encode
    :prog: vcf2zarr encode
    :nested: full

docs/vcf2zarr/overview.md

@@ -1,10 +1,39 @@
 (sec-vcf2zarr)=
 # vcf2zarr
 
-
 Convert VCF data to the
 [VCF Zarr specification](https://github.com/sgkit-dev/vcf-zarr-spec/)
-reliably, in parallel.
+reliably, in parallel or distributed over a cluster.
+
+See the {ref}`sec-vcf2zarr-tutorial` for a step-by-step introduction
+and the {ref}`sec-vcf2zarr-cli-ref` detailed documentation on
+command line options.
+
+
+## Quickstart
+
+First {ref}`install bio2zarr<sec-installation>`
+
+
+## How does it work?
+The conversion of VCF data to Zarr is a two-step process:
+
+1. Convert ({ref}`explode<cmd-vcf2zarr-explode>`) VCF file(s) to
+    Intermediate Columnar Format (ICF)
+2. Convert ({ref}`encode<cmd-vcf2zarr-encode>`) ICF to Zarr
+
+This two-step process allows `vcf2zarr` to determine the correct
+dimension of Zarr arrays corresponding to each VCF field, and
+to keep memory usage tightly bounded while writing the arrays.
+
+:::{important}
+The intermediate columnar format is not intended for any use
+other than a temporary storage while converting VCF to Zarr.
+The format may change between versions of `bio2zarr`.
+:::
+
+
+## Common options
 
 ```
 $ vcf2zarr convert <VCF1> <VCF2> <zarr>

docs/vcf2zarr/tutorial.md

@@ -9,6 +9,7 @@ kernelspec:
   language: bash
   name: bash
 ---
+(sec-vcf2zarr-tutorial)=
 # Tutorial
 
 This is a step-by-step tutorial showing you how to convert your