docs: fill in guidelines for module docs

README.md

@@ -13,11 +13,13 @@ These are general guidelines for writing official modules and their documentatio
 - Use `snake_case` for functions and variables changed by the code.
 - Use `SCREAMING_SNAKE_CASE` for variables that are set once and stay unchanged.
 
-### `module.yml` (not implemented) (will replace READMEs)
+### Documentation
 
-Each public module should also include a `module.yml` with the following keys: (TODO, not planned yet).
+Every public module should have a `module.yml` ([reference](https://blue-build.org/reference/module/#moduleyml)) file for metadata and a `README.md` file for an in-depth description. 
 
-#### `description:`
+For the documentation of the module in `README.md`, the following guidelines apply:
+- At the start of each _paragraph_, refer to the module using its name or with "the module", not "it" or "the script".
+- Use passive grammar when talking about the user, i.e. "should be used", "can be configured", preferring references to what the module does, i.e. "This module downloads the answer to the ultimate question of life, the universe and everything..." instead of what the user does, i.e. "A user can configure this module to download 42".
 
-- At the start of each paragraph, refer to the module using its name or with "the module", not "it" or "the script"
-- Use passive grammar when talking about the user, ie. "should be used", "can be configured", preferring references to what the module does, ie. "This module downloads the answer to the question of life, the universe and everything..."
+For the short module description (`shortdesc:`), the following guidelines apply:
+- The description should start with a phrase like "The glorb module reticulates splines" or "The tree module can be used to plant trees".