diff --git a/doc/git-annex-addcomputed.mdwn b/doc/git-annex-addcomputed.mdwn
new file mode 100644
index 0000000000..395d6246e7
--- /dev/null
+++ b/doc/git-annex-addcomputed.mdwn
@@ -0,0 +1,108 @@
+# NAME
+
+git-annex addcomputed - adds computed files to the repository
+
+# SYNOPSIS
+
+git annex addcomputed `--to=remote [--input name=file ...] [--value name=value ...] [--output name=file ...]`
+
+git annex addcomputed `--describe=remote`
+
+# DESCRIPTION
+
+Adds files to the annex that are computed from input files and values,
+using a compute special remote.
+
+For example, this adds a file `foo.jpeg` to the repository. It is computed
+by the "photoconv" compute remote, based on an input file, `foo.raw`. A
+configurable "passes" value is set to 10 when computing the file.
+
+    git-annex addcomputed --to photoconv \
+        --input raw=foo.raw --output photo=foo.jpeg \
+        --value passes=10
+
+There can be more than one input file that are combined to compute an
+output file. And multiple output files can be computed at the same time.
+
+The output files are added to the repository as annexed files.
+Once a file has been added to a compute remote, commands
+like `git-annex get` will use it to compute the content of the file.
+It is also possible to use commands like `git-annex drop` on the file,
+with the compute remote being counted as one copy of it.
+
+# OPTIONS
+
+* `--to=remote`
+
+  Specify which remote will compute the files. 
+
+  This must be a compute remote. For example, one can be
+  initialized with:
+
+    git-annex initremote photoconv type=compute \
+        program=git-annex-compute-photoconv
+
+  For details about compute remotes, and a list of some
+  of the programs that are available, see
+  <https://git-annex.branchable.com/special_remotes/compute/>
+
+* `--input name=file`
+
+  Provide a file as input to the computation, with the specified input name.
+
+  The input file can be an annexed file, or a file stored in git.
+
+* `--output name=file`
+
+  Add the output of the computation to the repository as an annexed file,
+  with the specified filename.
+
+* `--value name=value`
+
+  Provide a value to the computation, with the specified name.
+
+* `--describe=remote`
+
+  Describe all inputs, outputs, and values supported by a compute remote.
+
+  For a machine-readable list, use this with `--json`.
+
+* `--fast`
+
+  Adds computed files to the repository, without generating their content
+  yet. 
+
+* `--unreproducible`
+
+  Indicate that the computation is not expected to be fully reproducible.
+  It can vary, in ways that produce files that equivilant enough to
+  be interchangeable, but are not necessarily identical.
+
+  This is the default unless the compute remote indicates that it produces
+  reproducible output.
+
+* `--reproducible`, `-r`
+
+  Indicate that the computation is expected to be fully reproducible.
+
+  This is the default when the compute remote indicates that it produces
+  reproducible output.
+
+  If a computation turns out not to be fully reproducible, then getting
+  the file from the compute remote will later fail with a checksum
+  verification error. One thing that can be done then is to use 
+  `git-annex recompute --unreproducible`.
+
+*  Also the [[git-annex-common-options]](1) can be used.
+
+# SEE ALSO
+
+[[git-annex]](1)
+
+[[git-annex-recompute]](1)
+
+# AUTHOR
+
+Joey Hess <id@joeyh.name>
+
+Warning: Automatically converted into a man page by mdwn2man. Edit with care.
diff --git a/doc/git-annex-initremote.mdwn b/doc/git-annex-initremote.mdwn
index 0e4514e823..bcb3494b7f 100644
--- a/doc/git-annex-initremote.mdwn
+++ b/doc/git-annex-initremote.mdwn
@@ -52,7 +52,7 @@ want to use `git annex renameremote`.
 
 	git annex initremote mys3 type=S3 --whatelse
 
-  For a machine-readable list of the parameters, use this with --json.
+  For a machine-readable list of the parameters, use this with `--json`.
 
 * `--fast`
 
diff --git a/doc/git-annex-recompute.mdwn b/doc/git-annex-recompute.mdwn
new file mode 100644
index 0000000000..c86173c2eb
--- /dev/null
+++ b/doc/git-annex-recompute.mdwn
@@ -0,0 +1,55 @@
+# NAME
+
+git-annex recompute - update computed files
+
+# SYNOPSIS
+
+git-annex recompute [path ...]`
+
+# DESCRIPTION
+
+This updates computed files that were added with
+[[git-annex-addcomputed]](1).
+
+By default, this only recomputes files whose input files have changed.
+The new contents of the input files are used to re-run the computation,
+and when the output is different, the updated computed file is staged
+in the repository.
+
+# OPTIONS
+
+* `--unchanged`
+
+  Recompute files even when their input files have not changed.
+
+* `--unreproducible`
+
+  Convert files that were added with `git-annex addcomputed --reproducible`
+  to be as if they were added without that option.
+
+* `--reproducible`
+
+  Convert files that were added with `git-annex addcomputed --unreproducible`
+  to be as if they were added with `--reproducible`.
+
+* matching options
+
+  The [[git-annex-matching-options]](1) can be used to control what
+  files to recompute.
+
+  For example, to only recompute files that are computed by the "photoconv"
+  compute remote, use `--in=photoconv`
+
+*  Also the [[git-annex-common-options]](1) can be used.
+
+# SEE ALSO
+
+[[git-annex]](1)
+
+[[git-annex-addcomputed]](1)
+
+# AUTHOR
+
+Joey Hess <id@joeyh.name>
+
+Warning: Automatically converted into a man page by mdwn2man. Edit with care.
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 620aee61cd..85dda2b223 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -186,6 +186,18 @@ content from the key-value store.
   
   See [[git-annex-undo]](1) for details.
 
+* `addcomputed`
+
+  Adds computed files to the repository.
+
+  See [[git-annex-addcomputed]](1) for details.
+
+* `recompute`
+
+  Recomputes computed files.
+
+  See [[git-annex-recompute]](1) for details.
+
 * `multicast`
 
   Multicast file distribution.
diff --git a/doc/special_remotes/compute.mdwn b/doc/special_remotes/compute.mdwn
new file mode 100644
index 0000000000..b840f5fcbe
--- /dev/null
+++ b/doc/special_remotes/compute.mdwn
@@ -0,0 +1,33 @@
+While other remotes store the contents of annexed files somewhere,
+this special remote uses a program to compute the contents of annexed
+files.
+
+To enable an instance of this special remote:
+
+    # git-annex initremote myremote type=compute program=git-annex-compute-foo
+
+The `program` parameter is the only required parameter. It is the name of the
+program to use to compute the contents of annexed files. It must start with
+"git-annex-compute-". The program needs to be installed somewhere in the
+`PATH`.
+
+To add a file to a compute special remote, use the [[git-annex-addcomputed]]
+command. Once a file has been added to a compute special remote, commands
+like `git-annex get` will use it to compute the content of the file.
+
+You can provide other parameters to `initremote`, in order to provide
+default configuration values to use when adding files with
+[[git-annex-addcomputed]]. To see a list of all the configuration values
+supported by a given program, pass `--whatelse` to `initremote`:
+
+    # git-annex initremote myremote type=compute program=git-annex-compute-foo --whatelse
+
+## compute programs
+
+To write programs used by the compute special remote, see the 
+[[design/compute_special_remote_interface]].
+
+Have you written a generally useful (and secure) compute program?
+List it here!
+
+* ...