doc: document goal to have examples

mhdawson · xtx1130 · commit 65b4bd1e53b8 · 2022-04-25T17:43:10.000+08:00
As discussed in next-10 mini-summit on documentation see minutes where next steps were discussed - https://github.com/nodejs/next-10/blob/main/meetings/2022-02-16.md and minutes from summit - https://github.com/nodejs/next-10/blob/main/meetings/2022-02-16.md Signed-off-by: Michael Dawson <mdawson@devrus.com> PR-URL: nodejs#42274 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Mestery <mestery@protonmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Darshan Sen <raisinten@gmail.com>
diff --git a/doc/README.md b/doc/README.md
@@ -35,6 +35,8 @@ this guide.
   (`[a link](http://example.com)`).
 * When documenting APIs, update the YAML comment associated with the API as
   appropriate. This is especially true when introducing or deprecating an API.
+* When documenting APIs, every function should have a usage example or
+  link to an example that uses the function.
 * For code blocks:
   * Use [language][]-aware fences. (<code>\`\`\`js</code>)
 
