Add a note for package developers

README.md

@@ -112,6 +112,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