README.md

@@ -1,6 +1,7 @@
 # ido-completing-read+ (formerly ido-ubiquitous) #
 
 [![MELPA Stable](https://stable.melpa.org/packages/ido-completing-read+-badge.svg)](https://stable.melpa.org/#/ido-completing-read%2B)
+[![CI Status](https://github.com/DarwinAwardWinner/ido-completing-read-plus/actions/workflows/test.yml/badge.svg)](https://github.com/DarwinAwardWinner/ido-completing-read-plus/actions/workflows/test.yml)
 [![Join the chat at https://gitter.im/DarwinAwardWinner/ido-ubiquitous](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/DarwinAwardWinner/ido-ubiquitous?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 [![Coverage Status](https://coveralls.io/repos/github/DarwinAwardWinner/ido-completing-read-plus/badge.svg?branch=main)](https://coveralls.io/github/DarwinAwardWinner/ido-completing-read-plus?branch=main)
 
@@ -112,6 +113,11 @@ of them separately.
 * [Gnus](http://www.gnus.org/): `(setq gnus-completing-read-function 'gnus-ido-completing-read)`
 * [ESS](https://ess.r-project.org/): `(setq ess-use-ido t)`
 
+If you are a package author implementing ido support for *your*
+package, you should consider using `ido-completing-read+` in place of
+`ido-completing-read`, since it smooths out many of the unexpected
+edge cases of ido relative to `completing-read-default`.
+
 ## icomplete-mode ##
 
 For any case where ido cannot be used, there is another older mode

ido-completing-read+.el

@@ -30,7 +30,10 @@
 ;; standard completion instead. Hence, you can safely set
 ;; `completing-read-function' to `ido-completing-read+' without
 ;; worrying about breaking completion features that are incompatible
-;; with ido.
+;; with ido. (Package authors interested in implementing ido support
+;; within their packages can also use `ido-completing-read+' instead
+;; of `ido-completing-read' to provide a more consistent user
+;; experience.)
 
 ;; To use this package, call `ido-ubiquitous-mode' to enable the mode,
 ;; or use `M-x customize-variable ido-ubiquitous-mode' it to enable it