Suggest adoption of Google Style guide (#14905)

Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com>
This commit is contained in:
Charles Smith 2023-11-01 13:31:03 -07:00 committed by GitHub
parent 3860052de0
commit de557a62ad
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 46 additions and 3 deletions

View File

@ -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 discuss style-related convention that cannot be (or are extremely difficult to be) enforced through such automated
mechanisms. 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 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. 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")` * 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]"` * 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"` * 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).

View File

@ -131,9 +131,47 @@ The docs go through a review process similar to the code where community members
## Style guide ## 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 descriptive link text. If a link downloads a file, make sure to indicate this action.
* Use present tense where possible. * Use present tense where possible.