This is an automated email from the ASF dual-hosted git repository.
brile pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/druid.git
The following commit(s) were added to refs/heads/master by this push:
new de557a62adc Suggest adoption of Google Style guide (#14905)
de557a62adc is described below
commit de557a62adc4f252037ce7fd823df4767002b734
Author: Charles Smith <[email protected]>
AuthorDate: Wed Nov 1 13:31:03 2023 -0700
Suggest adoption of Google Style guide (#14905)
Co-authored-by: Victoria Lim <[email protected]>
---
dev/style-conventions.md | 7 ++++++-
docs/development/docs-contribute.md | 42 +++++++++++++++++++++++++++++++++++--
2 files changed, 46 insertions(+), 3 deletions(-)
diff --git a/dev/style-conventions.md b/dev/style-conventions.md
index 615e2fb703f..58cd052c114 100644
--- a/dev/style-conventions.md
+++ b/dev/style-conventions.md
@@ -36,7 +36,7 @@ While this page might discuss conventions that are also
enforced via said mechan
discuss style-related convention that cannot be (or are extremely difficult to
be) enforced through such automated
mechanisms.
-## Message Formatting (Logs and Exceptions)
+## Message formatting for logs and exceptions
The way that log and exception messages get formatted is an important part of
a project. Specifically, it is
important that there is consistency in formatting such that someone can easily
identify and interpret messages.
@@ -60,3 +60,8 @@ This consistency applies to both log *and* exception messages.
* Good: `log.info("Filter [%s] on column [%s] cannot be applied to type
[%s]", "is not null", "null", "INTEGER")`
* After interpolation, clear separation: `"Filter [is not null] on column
[null] cannot be applied to type [INTEGER]"`
* With interpolations removed, it is clear what happened, though still
hard to figure out which specific thing to adjust: `"Filter on column cannot be
applied to type"`
+
+
+## Documentation style
+
+For the majority of style considerations, the Apache Druid documentation
follows the [Google Developer Documentation Style
Guide](https://developers.google.com/style). For more details, see [Contribute
to Druid docs](../docs/development/docs-contribute.md#style-guide).
diff --git a/docs/development/docs-contribute.md
b/docs/development/docs-contribute.md
index 60664ae0ca5..1edce05cf59 100644
--- a/docs/development/docs-contribute.md
+++ b/docs/development/docs-contribute.md
@@ -131,9 +131,47 @@ The docs go through a review process similar to the code
where community members
## Style guide
-Before publishing new content or updating an existing topic, audit your
documentation using this checklist to make sure your contributions align with
existing documentation.
+Consistent style, formatting, and tone make documentation easier to consume.
+For the majority of style considerations, the Apache Druid documentation
follows the [Google Developer Documentation Style
Guide](https://developers.google.com/style).
+The style guide should serve as a point of reference to enable contributors
and reviewers to maintain documentation quality.
-Here are some general guidelines:
+### Notable style exceptions
+
+In some cases, Google Style might make the Druid docs more difficult to read
and understand. This section highlights those exceptions.
+
+#### SQL keyword syntax
+For SQL keywords and functions, use all caps, but do not use code font.
+
+:::tip
+
+**Correct**
+
+The UNNEST clause unnests array values.
+
+**Incorrect**
+
+The \`UNNEST\` clause unnests array values.
+:::
+
+
+#### Optional parameters and arguments
+
+For optional parameters and arguments, enclose the optional parameter and
leading command in brackets.
+
+:::tip
+
+**Correct**
+
+HUMAN_READABLE_BINARY_BYTE_FORMAT(value[, precision])
+
+**Incorrect**
+
+HUMAN_READABLE_BINARY_BYTE_FORMAT(value, \[precision])
+:::
+
+### Style checklist
+
+Before publishing new content or updating an existing topic, you can audit
your documentation using the following checklist to make sure your
contributions align with existing documentation:
* Use descriptive link text. If a link downloads a file, make sure to indicate
this action.
* Use present tense where possible.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
