From c81fcdc701e1bd34ade52e1c50665ca18dab2d2a Mon Sep 17 00:00:00 2001 From: Anton Gilgur <4970083+agilgur5@users.noreply.github.com> Date: Thu, 14 Sep 2023 10:01:46 -0400 Subject: [PATCH] docs: update style guidelines for documentation contributions (#11712) Signed-off-by: Anton Gilgur --- .spelling | 2 ++ docs/doc-changes.md | 12 +++++++----- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/.spelling b/.spelling index 7e2c6631178f..0e6d19f39d71 100644 --- a/.spelling +++ b/.spelling @@ -45,6 +45,7 @@ Dataflow DeleteObject DevOps Dex +EditorConfig EtcD EventRouter FailFast @@ -104,6 +105,7 @@ s3 SDKs ServiceAccount Sharding +shortcodes Singer.io Snyk Sumit diff --git a/docs/doc-changes.md b/docs/doc-changes.md index df6e369598c7..017ca30b8121 100644 --- a/docs/doc-changes.md +++ b/docs/doc-changes.md @@ -2,14 +2,16 @@ Docs help our customers understand how to use workflows and fix their own problems. -Doc changes are checked for spelling, broken links, and lint issues by CI. To check locally run `make docs`. +Doc changes are checked for spelling, broken links, and lint issues by CI. To check locally, run `make docs`. + +General guidelines: * Explain when you would want to use a feature. * Provide working examples. -* Use simple short sentences and avoid jargon. -* Format code using back-ticks to avoid it being reported spelling error. -* Avoid use title-case mid-sentence. E.g. instead of "the Workflow", write "the workflow". -* Headings should be title-case. E.g. instead of "and", write "And". +* Format code using back-ticks to avoid it being reported as a spelling error. +* Follow the recommendations in the official [Kubernetes Documentation Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/). + * Particularly useful sections include [Content best practices](https://kubernetes.io/docs/contribute/style/style-guide/#content-best-practices) and [Patterns to avoid](https://kubernetes.io/docs/contribute/style/style-guide/#patterns-to-avoid). + * **Note**: Argo does not use the same tooling, so the sections on "shortcodes" and "EditorConfig" are not relevant. ## Running Locally