소스 검색

Document new choice of writing style guide (#10634)

Damilola Oladele 1 년 전
부모
커밋
1c0ffc8994
2개의 변경된 파일20개의 추가작업 그리고 14개의 파일을 삭제
  1. 19 0
      docs/contributing/documentation_guidelines.md
  2. 1 14
      docs/contributing/general_guidelines.md

+ 19 - 0
docs/contributing/documentation_guidelines.md

@@ -7,6 +7,12 @@ depth: 1
 ---
 ```
 
+(writing_style_guide)=
+
+## Writing style guide
+
+To ensure consistency in tone and language, follow the [Google developer documentation style guide](https://developers.google.com/style) when writing the Wagtail documentation.
+
 ## Formatting recommendations
 
 Wagtail’s documentation uses a mixture of [Markdown](https://myst-parser.readthedocs.io/en/stable/syntax/syntax.html) and [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). We encourage writing documentation in Markdown first, and only reaching for more advanced reStructuredText formatting if there is a compelling reason.
@@ -20,6 +26,19 @@ Keep your sentences short, varied in length.
 
 Separate text with an empty line to create a new paragraph.
 
+### Latin phrases and abbreviations
+
+Try to avoid Latin phrases (such as `ergo` or `de facto`) and abbreviations (such as `i.e.` or `e.g.`), and use common English phrases instead. Alternatively, find a simpler way to communicate the concept or idea to the reader. The exception is `etc.` which can be used when space is limited.
+
+Examples:
+
+| Don't use this | Use this instead     |
+| -------------- | -------------------- |
+| e.g.           | for example, such as |
+| i.e.           | that is              |
+| viz.           | namely               |
+| ergo           | therefore            |
+
 ### Heading levels
 
 Use heading levels to create sections, and allow users to link straight to a specific section. Start documents with an `# h1`, and proceed with `## h2` and further sub-sections without skipping levels.

+ 1 - 14
docs/contributing/general_guidelines.md

@@ -2,20 +2,7 @@
 
 ## Language
 
-British English is preferred for user-facing text; this text should also be marked for translation (using the `django.utils.translation.gettext` function and `{% translate %}` template tag, for example). However, identifiers within code should use American English if the British or international spelling would conflict with built-in language keywords; for example, CSS code should consistently use the spelling `color` to avoid inconsistencies like `background-color: $colour-red`.
-
-### Latin phrases and abbreviations
-
-Try to avoid Latin phrases (such as `ergo` or `de facto`) and abbreviations (such as `i.e.` or `e.g.`), and use common English phrases instead. Alternatively, find a simpler way to communicate the concept or idea to the reader. The exception is `etc.` which can be used when space is limited.
-
-Examples:
-
-| Don't use this | Use this instead     |
-| -------------- | -------------------- |
-| e.g.           | for example, such as |
-| i.e.           | that is              |
-| viz.           | namely               |
-| ergo           | therefore            |
+British English is preferred for user-facing text; this text should also be marked for translation (using the `django.utils.translation.gettext` function and `{% translate %}` template tag, for example). However, identifiers within code should use American English if the British or international spelling would conflict with built-in language keywords; for example, CSS code should consistently use the spelling `color` to avoid inconsistencies like `background-color: $colour-red`. American English is also the preferred spelling style when writing documentation. Learn more about our documentation writing style in [](writing_style_guide).
 
 ## File names