update docs

doc/index.rst

@@ -8,14 +8,18 @@ Welcome to sourmash!
 
 sourmash is a command-line tool and Python library for computing
 `MinHash sketches <https://en.wikipedia.org/wiki/MinHash>`__ from DNA
-sequences, compare them to each other, and plot the results.  This
-allows you to estimate sequence similarity quickly and accurately.
+sequences, comparing them to each other, and plotting the results.
+This allows you to estimate sequence similarity between even very
+large data sets quickly and accurately.
 
 Please see the `mash <http://mash.readthedocs.io/en/latest/>`__
 software and the `mash paper (Ondov et al., 2016)
 <http://biorxiv.org/content/early/2015/10/26/029827>`__ for background
 information on how and why MinHash sketches work.
 
+To use sourmash, you must be comfortable with the UNIX command line;
+programmers may find the Python library and API useful as well.
+
 In brief,
 
 * ``sourmash`` provides command line utilities for creating, comparing,

doc/more-info.rst

@@ -6,3 +6,17 @@ Titus wrote a few blog posts on sourmash:
 * `Applying MinHash to cluster RNAseq samples <http://ivory.idyll.org/blog/2016-sourmash.html>`__
 
 * `MinHash signatures as ways to find samples, and collaborators? <http://ivory.idyll.org/blog/2016-sourmash-signatures.html>`__
+
+YAML format for the signature
+-----------------------------
+
+The YAML format is not necessarily final; this is a TODO item for future
+releases.  In particular, we'd like to update it to store more metadata
+for samples.
+
+Interoperability with mash
+--------------------------
+
+The default sketches computed by sourmash and mash are comparable, but
+we are still [working on ways to convert the file
+formats](https://github.com/marbl/Mash/issues/27).

sourmash_lib/__init__.py

@@ -17,7 +17,7 @@ class Estimators(object):
        E = Estimators(n=1000, ksize=31)
        E.add_sequence(dna)
        ...
-       E.jaccard(other_E)
+       similarity = E.jaccard(other_E)
 
     ``Estimator`` supports the pickle protocol.
     """