diff --git a/hledger/shell-completion/README.md b/hledger/shell-completion/README.md
index 2fd4e3a74..aed97ce02 100644
--- a/hledger/shell-completion/README.md
+++ b/hledger/shell-completion/README.md
@@ -81,29 +81,29 @@ Here is a place to track the status of shell completions in hledger packages. As
 
 ## zsh completions
 
-There are some [zsh completions](https://github.com/zsh-users/zsh-completions/blob/master/src/_hledger) in the zsh-completions repo.
+hledger completions are shipped with zsh: <https://github.com/zsh-users/zsh-completions/blob/master/src/_hledger>.
+They may be out of date, please help by updating them.
 
+## fish completions
 
-## Completions for other shells
+hledger completions are shipped with fish: <https://github.com/fish-shell/fish-shell/blob/master/share/completions/hledger.fish>
+They may be out of date, please help by updating them.
 
-You're welcome to add completion scripts for other shells. It should not be too
-hard! All available hledger options and commands are already there (generated by
-the Makefile).
+## Creating completions for other shells
 
-The generated text files with options and commands are: `commands.txt`,
-`generic-options.txt`, and `options-*.txt` where `*` is the subcommand.
+A rough guide:
 
-Instructions to add support for another shell:
+1. Create an m4 template for your completion script, eg `hledger-completion.SHELL.m4` where SHELL is the name of the new shell.
 
-1. Create e.g. `hledger-completion.fish.m4` as a template file.
+2. Add a rule in `Makefile` to transform this to `hledger-completion.SHELL`.
 
-2. Add a Make rule to transform it to `hledger-completion.fish`.
+3. The current hledger commands, options and command options are listed in
+   `commands.txt`, `generic-options.txt`, and `options-*.txt`, generated by the Makefile.
+   Use m4 to include these options and commands into `hledger-completion.SHELL.m4`.
+   See `hledger-completion.bash.m4` as an example.
 
-3. Use m4 commands to include hledger options and commands into your script
-   template. See `hledger-completion.bash.m4` as a reference.
+4. Use `make` and then `make hledger-completion.SHELL` to generate and test the completion script.
 
-4. Use `make` and then `make hledger-completion.fish` to create and test the
-   completion script.
-
-5. Finally, if everything is working, also add the generated artifact
-   `hledger-completion.fish` to the repo so that people can use it directly.
+5. Then: add the generated script `hledger-completion.SHELL` to the upstream shell repo, so that it will be easily available to users.
+   If that's not possible, add it here for now.
+   And if you can, please help to keep it up to date with new hledger releases.