docs: improve documentation on how to write documentation (#4771)

* docs: improve documentation on how to write documentation

* tweak

* tweak

* fix typo

---------

Co-authored-by: Yoshiya Hinosawa <stibium121@gmail.com>

.github/CONTRIBUTING.md

@@ -68,34 +68,60 @@ plain language, as follows:
 ## Documentation
 
 Symbols and modules are documented using the [JSDoc](https://jsdoc.app/) syntax.
-It should be written in the same style as the
-[MDN Web Docs](https://developer.mozilla.org/).
+These guidelines follow the recommendations in the blog post,
+[How to document your JavaScript package](https://deno.com/blog/document-javascript-package).
 
 ### Public symbols
 
-Documentation for public symbols should contain:
+Where applicable, documentation for public symbols should contain, in order:
 
-1. A description, first
-1. [`@param`](https://jsdoc.app/tags-param) tags for each parameter and a
-   [`@returns`](https://jsdoc.app/tags-returns) tag, if the symbol is a
-   function.
+1. A short description, then any further details in new paragraph(s).
+1. A `@typeParam` tag for each type parameter.
+1. A [`@param`](https://jsdoc.app/tags-param) tag for each parameter.
+1. A [`@returns`](https://jsdoc.app/tags-returns) tag for the return value.
 1. At least one example code snippet using the
-   [`@example`](https://jsdoc.app/tags-example) tag and a title. The code is
-   reproducible when copied and pasted as a script.
+   [`@example`](https://jsdoc.app/tags-example) tag and a title. See
+   [Example code snippets](#example-code-snippets) below for further guidance.
 
 See the source code within
-[`std/datetime`](https://github.com/denoland/deno_std/tree/main/datetime) for
+[`@std/bytes`](https://github.com/denoland/deno_std/tree/main/bytes) for
 examples.
 
+Once the documentation for a given package is written, add the package's entry
+point(s) (usually just `mod.ts`) to:
+
+1. The `ENTRY_POINTS` array in the
+   [documentation checker tool](../_tools/check_docs.ts).
+1. The `lint:docs` task in the
+   [`deno.json` file](https://github.com/denoland/deno_std/blob/main/deno.json).
+
+Once done, run `deno task lint:docs` which checks that documentation is complete
+in the given entry points.
+
 ### Module documentation
 
 Module files, or `mod.ts` files, should have the following:
 
 1. A high-level description of the package.
-1. Sections providing brief overviews of the APIs within the package, including
-   minimal example code snippets (without the `@example` tag).
-1. A [`@module`](https://jsdoc.app/tags-module) to denote module documentation.
+1. One example code snippet exhibiting a few APIs within the package. Do not
+   include the `@example` tag. See
+   [Example code snippets](#example-code-snippets) below for further guidance.
+1. A [`@module`](https://jsdoc.app/tags-module) tag to declare as module
+   documentation.
 
 See the source code for
-[`std/datetime/mod.ts`](https://github.com/denoland/deno_std/blob/main/datetime/mod.ts)
+[`@std/bytes/mod.ts`](https://github.com/denoland/deno_std/blob/main/bytes/mod.ts)
 as an example.
+
+### Example code snippets
+
+Example code snippets must:
+
+1. Be as simple yet readable as possible. When in doubt, refer to MDN's
+   [Guidelines for writing JavaScript code examples](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript).
+1. Be reproducible as a copied and pasted script.
+1. Use an assertion from [`@std/assert`](https://jsr.io/@std/assert), when
+   possible. Snippets are run using
+   [`deno eval`](https://docs.deno.com/runtime/manual/tools/eval) in the
+   [documentation checker tool](../_tools/check_docs.ts) and are flagged when
+   they throw an error.