update best practices file

[sivanel97]

User description

Description

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.

Added docs pages

Please also include the path for the added docs

• Quickstart (/)
• Blueprint (/platform-overview/port-components/blueprint)
• ...

Updated docs pages

Please also include the path for the updated docs

• Quickstart (/)
• Blueprint (/platform-overview/port-components/blueprint)
• ...

---

PR Type

Documentation

---

Description

• Restructured best practices file with 22 detailed documentation patterns

• Moved specific guidelines into collapsible pattern examples with discussion links

• Consolidated redundant sections and removed duplicated content

• Created archived copy of original guidelines in best_practices_old.md

---

Diagram Walkthrough

flowchart LR
  A["Original best_practices.md"] -->|Restructured| B["22 Documentation Patterns"]
  B -->|Pattern Examples| C["Before/After Code Examples"]
  B -->|Discussion Links| D["Collapsible Details Sections"]
  A -->|Archived| E["best_practices_old.md"]

Loading

File Walkthrough

Relevant files

Documentation

best_practices.md Restructure with 22 documented patterns and examples          best_practices.md Replaced generic styling guidelines with 22 specific, actionable documentation patterns (Patterns 1-22) Each pattern includes before/after code examples and collapsible discussion link sections Consolidated redundant content from "Tone & style", "Technical writing best practices", "Tabs", "Links", "Code examples", and "Summary/details" sections into pattern-based approach Moved specific rules (e.g., showLineNumbers, capitalization, admonition titles) into relevant patterns Simplified remaining "Additional guidelines" section by removing duplicated rules now covered in patterns Removed old "Styling guidelines" section header structure +607/-66 best_practices_old.md Archive original best practices guidelines                              best_practices_old.md Created new archive file containing the original best practices content Preserves previous version of guidelines for reference and historical tracking Contains all original sections including styling guidelines, tone & style, technical writing best practices, tabs, links, lists, images, code examples, and admonitions +161/-0

---

[qodo-merge-pro]

PR Compliance Guide 🔍

(Compliance updated until commit 260195d)

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Not Applicable: The PR only restructures documentation content and adds style patterns; no executable code paths for critical actions or logging were introduced to assess audit trail compliance. Referred Code <b>Pattern 1: Always standardize collapsible details with bold titles and "(click to expand)" for consistency and usability across docs.</b> Example code before: Repository blueprint Content goes here ``` Example code after: <details> <summary><b>Repository blueprint (click to expand)</b></summary> Content goes here ... (clipped 677 lines)
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Docs Only Changes: Changes are Markdown documentation and examples, not application identifiers or functions, so naming conventions in code cannot be evaluated. Referred Code <b>Pattern 1: Always standardize collapsible details with bold titles and "(click to expand)" for consistency and usability across docs.</b> Example code before: Repository blueprint Content goes here ``` Example code after: <details> <summary><b>Repository blueprint (click to expand)</b></summary> Content goes here ... (clipped 677 lines)
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: No Runtime Code: The PR modifies documentation and illustrative snippets only; no production error handling paths were added or changed to assess robustness or edge-case handling. Referred Code <b>Pattern 1: Always standardize collapsible details with bold titles and "(click to expand)" for consistency and usability across docs.</b> Example code before: Repository blueprint Content goes here ``` Example code after: <details> <summary><b>Repository blueprint (click to expand)</b></summary> Content goes here ... (clipped 677 lines)
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Not Applicable: No user-facing error messages or handlers were introduced; only documentation content was changed, so secure error handling cannot be assessed. Referred Code <b>Pattern 1: Always standardize collapsible details with bold titles and "(click to expand)" for consistency and usability across docs.</b> Example code before: Repository blueprint Content goes here ``` Example code after: <details> <summary><b>Repository blueprint (click to expand)</b></summary> Content goes here ... (clipped 677 lines)
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: No Logging Code: The PR adds documentation patterns and examples without introducing or modifying application logging, so secure logging practices cannot be validated. Referred Code <b>Pattern 1: Always standardize collapsible details with bold titles and "(click to expand)" for consistency and usability across docs.</b> Example code before: Repository blueprint Content goes here ``` Example code after: <details> <summary><b>Repository blueprint (click to expand)</b></summary> Content goes here ... (clipped 677 lines)
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: No Input Handling: The changes are to documentation only and do not add input processing, storage, or transmission code that could be assessed for validation and secure handling. Referred Code <b>Pattern 1: Always standardize collapsible details with bold titles and "(click to expand)" for consistency and usability across docs.</b> Example code before: Repository blueprint Content goes here ``` Example code after: <details> <summary><b>Repository blueprint (click to expand)</b></summary> Content goes here ... (clipped 677 lines)

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

---

Previous compliance checks

Compliance check up to commit efc8734

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Not Applicable: The PR only updates documentation content and does not introduce or modify executable code or logging behavior; no audit trail implementation can be assessed from the diff. Referred Code <b>Pattern 1: Always standardize collapsible details with bold titles and "(click to expand)" for consistency and usability across docs.</b> Example code before: Repository blueprint Content goes here ``` Example code after: <details> <summary><b>Repository blueprint (click to expand)</b></summary> Content goes here ... (clipped 677 lines)
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Not Applicable: The PR adds documentation guidelines and examples without executable logic or error handling paths; no error handling behavior is present to review. Referred Code <b>Pattern 1: Always standardize collapsible details with bold titles and "(click to expand)" for consistency and usability across docs.</b> Example code before: Repository blueprint Content goes here ``` Example code after: <details> <summary><b>Repository blueprint (click to expand)</b></summary> Content goes here ... (clipped 677 lines)

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Reconsider the verbose pattern-based format The current pattern-based format is overly verbose and repetitive; consider a more concise structure by grouping related rules under thematic headings to improve scannability and maintainability. Examples: best_practices.md [5-602] <b>Pattern 1: Always standardize collapsible details with bold titles and "(click to expand)" for consistency and usability across docs.</b> Example code before: Repository blueprint Content goes here ... (clipped 588 lines) </details> ### Solution Walkthrough: #### Before: ```markdown <b>Pattern 1: Rule about collapsible details...</b> Example code before: ... Example code after: ... ___ <b>Pattern 2: Rule about headings and lists...</b> Example code before: ... Example code after: ... ___ ... (20 more patterns follow this structure) After: ## Formatting and Structure ### Collapsible Details Rule: Always standardize collapsible details with bold titles and "(click to expand)". <details><summary>Example</summary> **Before:** ... **After:** ... </details> ### Headings and Lists Rule: Use sentence case for headers and periods at the end of bullet items. ... (with example) ... ## Tone & Style ### Voice and Tone Rule: Use "We" language instead of commanding "You" language. ... (with example) ... Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a major drawback of the PR's approach—the new format is extremely verbose, which could harm readability and maintainability—and proposes a valid alternative that balances explicitness with conciseness.	Medium
Organization best practice	Resolve tone guidance conflict Add an explicit note reconciling this with the later "We" language pattern to avoid conflicting guidance and confusion for contributors. best_practices.md [613] - When addressing the reader, use second-person pronouns (you, your). For example "You can achieve this by…". +- Use "We" language in guides to frame steps collaboratively (see Pattern 9). Prefer second-person for explanations; prefer "We" for step-by-step guidance. Apply / Chat Suggestion importance[1-10]: 6 __ Why: Relevant best practice - Avoid contradictions and maintain consistency across guidelines.	Low
General	Use modern HTML and specify language Update the code examples in Pattern 13 to use the html language specifier and replace the obsolete border attribute with modern inline CSS for styling. best_practices.md [337-352] <b>Pattern 13: Format images with proper width, border, and full path to ensure consistent display and prevent blending with background.</b> Example code before: -``` +```html <img src='../img/screenshot.png' /> <img src='./images/example.png' /> Example code after: - -<img src='/img/software-catalog/pages/excludePropertiesForm.png' width='50%' border='1px' alt='Form showing property exclusion options' /> +html + Note: Images should be saved under `/static/img/` in the relevant directory. Always include alt text for accessibility. Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion correctly points out two valid improvements: specifying the language for the code block as per the new guidelines, and replacing the obsolete HTML border attribute with modern CSS styling.	Low
	Specify language for code blocks Add the html language specifier to the code blocks in Pattern 1 to enable syntax highlighting, following the guidelines established in Patterns 4 and 14. best_practices.md [5-27] <b>Pattern 1: Always standardize collapsible details with bold titles and "(click to expand)" for consistency and usability across docs.</b> Example code before: -``` +```html <details> <summary>Repository blueprint</summary> Content goes here </details> Example code after: - +html Repository blueprint (click to expand) Content goes here ``` ``` Apply / Chat Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies that the code blocks in Pattern 1 are missing the language specifier, which is inconsistent with the new guidelines introduced in Pattern 4 and Pattern 14 within the same document.	Low
	Apply sentence case to headers Update the headers Tone & style and Images & GIFs to use sentence case (Tone and style, Images and GIFs) to align with the new documentation guidelines. best_practices.md [608-681] -### Tone & style +### Tone and style ... -### Images & GIFs +### Images and GIFs ... ### Formatting standards [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies that the headers Tone & style and Images & GIFs do not follow the sentence case rule established in the new patterns, improving document consistency.	Low
Update

[aws-amplify-eu-west-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2971.d2ngvl90zqbob8.amplifyapp.com