Skip to content

Commit

Permalink
Suggest adoption of Google Style guide (#14905)
Browse files Browse the repository at this point in the history
Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com>
  • Loading branch information
techdocsmith and vtlim authored Nov 1, 2023
1 parent 3860052 commit de557a6
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 3 deletions.
7 changes: 6 additions & 1 deletion dev/style-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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).
42 changes: 40 additions & 2 deletions docs/development/docs-contribute.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit de557a6

Please sign in to comment.