diff --git a/best_practices.md b/best_practices.md index 3c1607275b..63c638d40b 100644 --- a/best_practices.md +++ b/best_practices.md @@ -1,5 +1,19 @@ # Port documentation style guide +___ + +**Header capitalization rules:** Use sentence case for headers with only the first word capitalized. + +❌ "## Sync Approaches And Methods" +✅ "## Sync approaches and methods" + +Note: Well-known product names such as Lambda, Kubernetes, ArgoCD, etc. should follow their standard capitalization rules and styling. + +❌ "aws" +✅ "AWS" + +___ + This document details guidelines for contributing to Port's documentation, and demonstrates how to correctly write and review documentation content. Pattern 1: Always standardize collapsible details with bold titles and "(click to expand)" for consistency and usability across docs. @@ -208,18 +222,6 @@ Example code after: ___ -**Header capitalization rules:** Use sentence case for headers with only the first word capitalized. - -❌ "## Sync Approaches And Methods" -✅ "## Sync approaches and methods" - -Note: Well-known product names such as Lambda, Kubernetes, ArgoCD, etc. should follow their standard capitalization rules and styling. - -❌ "aws" -✅ "AWS" - -___ - Pattern 9: Use "We" language instead of commanding "You" language to create a collaborative, guiding tone rather than issuing commands. Example code before: @@ -683,4 +685,4 @@ Before submitting your contribution, review it against this checklist: - [ ] Tone is consistent with Port's documentation style - [ ] Content is organized logically - [ ] Technical terms are explained or linked to definitions -- [ ] No unnecessary jargon or marketing language \ No newline at end of file +- [ ] No unnecessary jargon or marketing language