diff --git a/dev/style-conventions.md b/dev/style-conventions.md index 615e2fb703f2..58cd052c1149 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 60664ae0ca5d..1edce05cf599 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.