From 2631e7d1515ce8b4d4c4d82e3451c6dc12a9ce69 Mon Sep 17 00:00:00 2001 From: Anton Gilgur Date: Thu, 24 Oct 2024 12:36:56 -0400 Subject: [PATCH] docs: add some existing conventions to the style guide just a few that have recently been mentioned off the top of my head: - relative links - "Argo" vs. "Argo Workflows" - In-line version annotations - embedded example files Signed-off-by: Anton Gilgur --- docs/doc-changes.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/doc-changes.md b/docs/doc-changes.md index 580b9de98b74..83cf836db32c 100644 --- a/docs/doc-changes.md +++ b/docs/doc-changes.md @@ -8,8 +8,14 @@ General guidelines: * Explain when you would want to use a feature. * Provide working examples. + * Prefer to [embed files](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#embedding-external-files) from the `examples/` directory. * Format code using back-ticks to avoid it being reported as a spelling error. -* Prefer 1 sentence per line of markdown +* Prefer 1 sentence per line of markdown. +* Internally, refer to "Argo Workflows" as "Argo", unless a disambiguation is needed (such as when integrating with Argo CD). +* Use relative links to other pages or sections + * For example, `[architecture](architecture.md)` +* When documenting a new feature, add an in-line version annotation + * For example, `> v3.6 and after` * 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.