diff --git a/doc/git-annex-addcomputed.mdwn b/doc/git-annex-addcomputed.mdwn
index 395d6246e7..487bb70ff1 100644
--- a/doc/git-annex-addcomputed.mdwn
+++ b/doc/git-annex-addcomputed.mdwn
@@ -4,31 +4,34 @@ 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`
+git annex addcomputed `--to=remote -- ...`
 
 # DESCRIPTION
 
-Adds files to the annex that are computed from input files and values,
+Adds files to the annex that are computed from input files,
 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.
+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.
 
-    git-annex addcomputed --to photoconv \
-        --input raw=foo.raw --output photo=foo.jpeg \
-        --value passes=10
+The syntax of this command after the `--` is up to the program that
+the compute special remote is set up to run to perform the comuptation.
+
+To see the program's usage, you can run:
+
+    git-annex addcomputed --to=foo
+
+Generally you will provide an input file (or files), and often also an
+output filename, and additional parameters to control the computation.
 
 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.
+Some examples of how this might look:
+
+    git-annex addcomputed --to=x -- convert file.raw file.jpeg passes=10
+    git-annex addcomputed --to=y -- compress foo --level=9
+    git-annex addcomputed --to=z -- clip foo 2:01-3:00 combine with bar to baz
 
 # OPTIONS
 
@@ -46,27 +49,6 @@ with the compute remote being counted as one copy of it.
   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