service/documentation.md

@@ -138,6 +138,15 @@ with guides for... exactly the same list! So instead we flip that
 structure around and the top-level structure is by service: within
 those pages we follow the suggested structure.
 
+### Style
+
+Writing style in the documentation is currently lose and not formally
+documented. But we should probably settle on some english-based,
+official, third-party style guide to provide guidance and
+resources. The [Vue documentation](https://v3.vuejs.org/guide/) has a [great writing &
+grammar section](https://v3.vuejs.org/guide/contributing/writing-guide.html#writing-grammar) which could form a basis here, as well as [Jacob
+Kaplan-Moss's Technical Style](https://jacobian.org/2009/nov/11/technical-style/) article.
+
 ### Authentication
 
 The entire wiki is public and no private or sensitive information
@@ -269,6 +278,14 @@ like indexes, hierarchical (and automatic) sidebars (based on
 structure, e.g. [Sphinx](https://www.sphinx-doc.org/) or [mkdocs](https://www.mkdocs.org/)), paging, per-section RSS
 feeds (for "blog" or "news" type functionality) and so on.
 
+The "Tutorial/Howto/Reference/Discussion" structure is not as intuitive
+as one author might like to think. We might be better reframing this
+in the context of a service, for example merging the "Discussion" and
+"Reference" section, and moving the "Goals/alternatives considered"
+section into an (optional?)  "Migration" section, since that is really
+what the discussion section is currently used for (planning major
+service changes and improvements).
+
 ### Syntax
 
 Markdown is great for jotting down notes, filing issues and so on, but
@@ -289,6 +306,17 @@ than the alternatives (e.g. asciidoc or rst), for better or for
 worse. So it might be better to stick with it than to force users to
 learn a new markup language, however good it is supposed to be.
 
+### Editing
+
+Since few people are currently contributing to the documentation, few
+people review changes done to it. As [Jacob Kaplan-Moss quipped](https://jacobian.org/2009/nov/12/editors/):
+
+> All good writers have a dirty little secret: they’re not really that
+> good at writing. Their editors just make it seem that way.
+
+In other words, we'd need a technical writer to review our docs, or at
+least setup a self-editing process the way Kaplan-Moss suggests above.
+
 ## Goals
 
 Note: considering we *just* migrated from ikiwiki to GitLab wikis, it