Merge pull request plone#1404 from plone/writing-docs-tips

stevepiercy · web-flow · commit 1adc82b5f93f · 2023-02-15T21:14:07.000-08:00
Overhaul Contributing to Documentation
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -1 +1 @@
-See our [contributing guidelines](https://6.dev-docs.plone.org/contributing/index.html).
+See our [contributing guidelines](https://6.docs.plone.org/contributing/index.html).
diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md
@@ -2,9 +2,10 @@ Thank you for your contribution to the Plone Documentation.
 
 Before submitting this pull request, please make sure you follow our guides:
 
-- [ ] [Contributing to Plone Documentation](https://6.dev-docs.plone.org/contributing/index.html)
-- [ ] [Building and Checking the Quality of Documentation](https://6.dev-docs.plone.org/contributing/setup-build.html)
-- [ ] [General Guide to Writing Documentation](https://6.dev-docs.plone.org/contributing/writing-docs-guide.html)
+-   [Contributing to Plone documentation](https://6.docs.plone.org/contributing/index.html)
+-   [Building and checking the quality of documentation](https://6.docs.plone.org/contributing/setup-build.html)
+-   [Authors guide](https://6.docs.plone.org/contributing/authors.html)
+-   [MyST reference](https://6.docs.plone.org/contributing/myst-reference.html)
 
 ## Issue Number
 
diff --git a/docs/conf.py b/docs/conf.py
@@ -52,12 +52,12 @@
     "sphinx_sitemap",
     "sphinxcontrib.httpdomain",  # plone.restapi
     "sphinxcontrib.httpexample",  # plone.restapi
+    "sphinxcontrib.video",
     "sphinxext.opengraph",
     "sphinx.ext.viewcode",  # plone.api
     "sphinx.ext.autosummary",  # plone.api
     "sphinx.ext.graphviz",
     "notfound.extension",
-    "sphinxcontrib.video",
 ]
 
 graphviz_output_format = "svg"
@@ -155,7 +155,7 @@
     #  instead of ```.
     "substitution",  # plone.restapi \
     # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2
-    "html_image",
+    "html_image",  # For inline images. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
 ]
 
 myst_substitutions = {
diff --git a/docs/contributing/authors.md b/docs/contributing/authors.md
@@ -9,46 +9,22 @@ myst:
 
 (authors-guide-label)=
 
-# Authors Guide
+# Authors guide
 
 This guide is for authors of Plone Documentation.
-It covers configuring quality checks and syntax for writing markup that is of particular interest to authors.
-For general markup syntax, see {doc}`writing-docs-guide`.
+It covers how to run a live preview of documentation while editing, build documentation, and perform quality checks.
+For general markup syntax, see {doc}`myst-reference`.
 
 
-(authors-html-meta-data-label)=
-
-## HTML and Open Graph Metadata
-
-All documents must have a `myst` topmatter key with an `html_meta` directive at the top of every page.
-When rendered to HTML, it inserts `<meta>` tags for improved search engine results and nicer social media posts.
-Authors should include at least `description`, `property=og:description`, `property=og:title`, and `keywords` meta tags.
-
-The following is an example of `html_meta`.
-Note that the content of the two tags `description` and `property=og:description` should be identical.
-
-```md
----
-myst:
-  html_meta:
-    "description": "Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors."
-    "property=og:description": "Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors."
-    "property=og:title": "Authors Guide"
-    "keywords": "Plone, Documentation, SEO, meta, Vale, spell, grammar, style, check, linkcheck, lexer"
----
-```
+## Synchronize the browser while editing
 
-This renders in the HTML `<head>` section as follows.
+Use `sphinx-autobuild` to view changes in the browser while you edit documentation.
 
-```html
-<meta content="Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." name="description" />
-<meta content="Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." property="og:description" />
-<meta content="Authors Guide" property="og:title" />
-<meta content="Plone, Documentation, SEO, meta, Vale, spell, grammar, style, check, linkcheck, lexer" name="keywords" />
+```shell
+make livehtml
 ```
 
-Additional {term}`Open Graph` metadata is implemented through the Sphinx extension [`sphinxext-opengraph`](https://github.com/wpilibsuite/sphinxext-opengraph) and the [MyST `html_meta` directive](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#setting-html-metadata), which resolves to the [Docutils `meta` directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata).
-See the site-wide configuration in {file}`conf.py`.
+You can open a browser at http://127.0.0.1:8000/ to preview the documentation.
 
 
 (authors-quality-checks-label)=
@@ -62,7 +38,7 @@ We strive for high quality documentation, setting the following minimum standard
 
 ### Markup syntax must be valid
 
-See both the specific markup syntax above and general markup in {doc}`writing-docs-guide`.
+See both the specific markup syntax above and general markup in {doc}`myst-reference`.
 
 To validate markup, run the following command.
 
@@ -75,7 +51,7 @@ Open `/_build/html/index.html` in a web browser.
 
 (authors-english-label)=
 
-### American English Spelling, Grammar, and Syntax, and Style Guide
+### American English spelling, grammar, and syntax, and style guide
 
 Spellings are enforced through [`Vale`](https://vale.sh/).
 Plone uses American English.
@@ -85,17 +61,18 @@ Spelling is configured in {file}`Makefile`, {file}`.vale.ini`, and in files in `
 Authors should add new words and proper names using correct casing to {file}`styles/Vocab/Plone/accept.txt`, sorted alphabetically and case-insensitive.
 
 Vale also provides English grammar and syntax checking, as well as a Style Guide.
+We follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
 
 To perform all these checks, run the following command.
 
 ```shell
 make vale
 ```
 
-Because it is difficult to automate good English grammar and syntax, we do not strictly enforce it.
+Because it is difficult to automate good American English grammar and syntax, we do not strictly enforce it.
 We also understand that contributors might not be fluent in English.
-We encourage contributors to make a reasonable effort, and to seek help from community members who are fluent in English.
-When you submit a pull request, please select a Reviewer to review your work.
+We encourage contributors to make a reasonable effort, and to request a review of their pull request from community members who are fluent in English to fix grammar and syntax.
+Please ask!
 
 
 (authors-linkcheck-label)=
@@ -188,7 +165,7 @@ If no other lexer works well, then fall back to `text`.
 At least then the build will succeed without warnings, although syntax highlighting for such snippets will not appear.
 
 
-#### Validate the Lexer
+#### Validate the lexer
 
 Always build the page to validate syntax.
 The change should not be merged if there are any Sphinx warnings.
@@ -220,12 +197,73 @@ When using the online lexer, if any red-bordered rectangles appear, then the lex
 You can search the [Pygments issue tracker](https://github.com/pygments/pygments/search) for possible solutions, or submit a pull request to enhance the lexer.
 
 
-## Synchronize the Browser While Editing
+(authors-html-meta-data-label)=
 
-Use `sphinx-autobuild` to view changes in the browser while editing documentation.
+### HTML and Open Graph metadata
 
-```shell
-make livehtml
+All documents must have a `myst` topmatter key with an `html_meta` directive at the top of every page.
+When rendered to HTML, it inserts `<meta>` tags for improved search engine results and nicer social media posts.
+Authors should include at least `description`, `property=og:description`, `property=og:title`, and `keywords` meta tags.
+
+The following is an example of `html_meta`.
+Note that the content of the two tags `description` and `property=og:description` should be identical.
+
+```md
+---
+myst:
+  html_meta:
+    "description": "Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors."
+    "property=og:description": "Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors."
+    "property=og:title": "Authors Guide"
+    "keywords": "Plone, Documentation, SEO, meta, Vale, spell, grammar, style, check, linkcheck, lexer"
+---
 ```
 
-You can open a browser at http://127.0.0.1:8000/ to preview the documentation.
+This renders in the HTML `<head>` section as follows.
+
+```html
+<meta content="Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." name="description" />
+<meta content="Authors' guide to writing Plone Documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." property="og:description" />
+<meta content="Authors Guide" property="og:title" />
+<meta content="Plone, Documentation, SEO, meta, Vale, spell, grammar, style, check, linkcheck, lexer" name="keywords" />
+```
+
+Additional {term}`Open Graph` metadata is implemented through the Sphinx extension [`sphinxext-opengraph`](https://github.com/wpilibsuite/sphinxext-opengraph) and the [MyST `html_meta` directive](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#setting-html-metadata), which resolves to the [Docutils `meta` directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata).
+See the site-wide configuration in {file}`conf.py`.
+
+
+## Plone documentation styleguide
+
+We follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
+
+Key concepts from that guide include the following.
+
+-   Documentation should be informational, but friendly.
+-   Address the reader by using "you" instead of "the user".
+-   Headings should be Sentence cased, not Title Cased.
+
+The Plone Documentation Team adopted additional guidelines.
+
+-   Use one sentence per line.
+    Keep sentences short and understandable.
+    This will greatly improve the editing and maintenance of your documentation.
+
+-   Do not follow PEP8 maximum line length standard.
+    Documentation is narrative text and images, not Python code.
+
+-   Use dashes `-` in filenames and avoid underscores.
+
+-   Images should be no wider than 740 pixels to fit within the documentation's main view port.
+    This avoids scaling and reducing legibility of images.
+    To make that work in Volto, set your browser width to 1180 pixels.
+    You will notice that the drag and trash icons for each block move inside the block from outside.
+
+-   In user documentation, provide screenshots of each step where the interface changes.
+    It is painstaking, but worth the effort.
+    Provide sufficient detail of what each option is and does.
+
+
+## General documentation writing references
+
+-   [Write the Docs - Documentation Guide](https://www.writethedocs.org/guide/)
+-   [A Guide to Em Dashes, En Dashes, and Hyphens](https://www.merriam-webster.com/words-at-play/em-dash-en-dash-how-to-use)
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
@@ -9,7 +9,7 @@ myst:
 
 (contributing-index-label)=
 
-# Contributing to Documentation
+# Contributing to documentation
 
 This document describes how to contribute to Plone Documentation.
 
@@ -36,15 +36,15 @@ A copy of the license is included in the root of this repository.
 
 (contributing-roles-label)=
 
-## Contributor Roles
+## Contributor roles
 
 Contributors to the Plone Documentation may perform one or many roles.
 
 - **Plone users and developers** use this documentation because it is accurate and actively maintained.
   People in these roles typically contribute minor corrections.
-  They should read {doc}`setup-build` and {doc}`writing-docs-guide`.
+  They should read {doc}`setup-build` and {doc}`myst-reference`.
 - **Authors** create Plone Documentation.
-  They should read {doc}`setup-build` and {doc}`writing-docs-guide`.
+  They should read {doc}`setup-build` and {doc}`myst-reference`.
   They should also read {doc}`authors` for guidance and tips for writing good technical documentation.
 
 
@@ -287,7 +287,8 @@ hidden: true
 ---
 
 setup-build
-writing-docs-guide
 authors
+myst-reference
+sphinx-extensions
 admins
 ```
diff --git a/docs/contributing/myst-reference.md b/docs/contributing/myst-reference.md
diff --git a/docs/contributing/sphinx-extensions.md b/docs/contributing/sphinx-extensions.md

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-See our [contributing guidelines](https://6.dev-docs.plone.org/contributing/index.html).`
	`1`	`+See our [contributing guidelines](https://6.docs.plone.org/contributing/index.html).`