add heading ID suggester script file and workflow

[logu-c8y]

No description provided.

[github-actions]

No heading ID suggestions

[github-actions]

Preview available here

[github-actions]

Heading ID suggestions:

• content/additional-resources/more-resources.md: “Tech Community” → {#tech-community}

[github-actions]

Suggested ID for this heading:

Suggested change

	### Tech Community {#tech-community}

[github-actions]

Heading ID suggestions:

• content/additional-resources/more-resources.md: “Tech Community” → {#tech-community}
• content/additional-resources/more-resources.md: “Cloud environments status” → {#cloud-environments-status}

[github-actions]

Suggested ID for this heading:

Suggested change

	### Tech Community {#tech-community}

[github-actions]

Suggested ID for this heading:

Suggested change

	### Cloud environments status {#cloud-environments-status}

[github-actions]

Heading ID suggestions:

• content/additional-resources/more-resources.md: “Tech Community” → {#tech-community}
• content/additional-resources/more-resources.md: “Cloud environments status” → {#cloud-environments-status}
• scripts/copilot-instructions.md: “Cumulocity Documentation Style Guide - Copilot Instructions” → {#cumulocity-documentation-style-guide-copilot-instructions}
• scripts/copilot-instructions.md: “Primary Objective” → {#primary-objective}
• scripts/copilot-instructions.md: “Writing Principles” → {#writing-principles}
• scripts/copilot-instructions.md: “Grammar & Language Rules” → {#grammar-language-rules}
• scripts/copilot-instructions.md: “Capitalization” → {#capitalization}
• scripts/copilot-instructions.md: “Voice & Tense” → {#voice-tense}
• scripts/copilot-instructions.md: “Articles & Modifiers” → {#articles-modifiers}
• scripts/copilot-instructions.md: “Punctuation Rules” → {#punctuation-rules}
• scripts/copilot-instructions.md: “Sentence Structure” → {#sentence-structure}
• scripts/copilot-instructions.md: “Serial (Oxford) Commas” → {#serial-oxford-commas}
• scripts/copilot-instructions.md: “End Punctuation - Skip When Appropriate” → {#end-punctuation-skip-when-appropriate}
• scripts/copilot-instructions.md: “List Punctuation” → {#list-punctuation}
• scripts/copilot-instructions.md: “Terminology Standards” → {#terminology-standards}
• scripts/copilot-instructions.md: “Prohibited Terms” → {#prohibited-terms}
• scripts/copilot-instructions.md: “UI Element Formatting” → {#ui-element-formatting}
• scripts/copilot-instructions.md: “Specific Word Choices” → {#specific-word-choices}
• scripts/copilot-instructions.md: “Structure & Organization” → {#structure-organization}
• scripts/copilot-instructions.md: “Headings” → {#headings}
• scripts/copilot-instructions.md: “Lists” → {#lists}
• scripts/copilot-instructions.md: “Procedures” → {#procedures}
• scripts/copilot-instructions.md: “Code & Technical Elements” → {#code-technical-elements}
• scripts/copilot-instructions.md: “Code Formatting” → {#code-formatting}
• scripts/copilot-instructions.md: “Links” → {#links}
• scripts/copilot-instructions.md: “Special Formatting” → {#special-formatting}
• scripts/copilot-instructions.md: “Notes & Callouts” → {#notes-callouts}
• scripts/copilot-instructions.md: “Capitalization Rules” → {#capitalization-rules}
• scripts/copilot-instructions.md: “Variables” → {#variables}
• scripts/copilot-instructions.md: “Content Organization Checklist” → {#content-organization-checklist}
• scripts/copilot-instructions.md: “Quality Check” → {#quality-check}

[github-actions]

Suggested ID for this heading:

Suggested change

	### Tech Community {#tech-community}

[github-actions]

Suggested ID for this heading:

Suggested change

	### Cloud environments status {#cloud-environments-status}

[github-actions]

Suggested ID for this heading:

Suggested change

	# Cumulocity Documentation Style Guide - Copilot Instructions {#cumulocity-documentation-style-guide-copilot-instructions}

[github-actions]

Suggested ID for this heading:

Suggested change

	Generate clear, comprehensive, and consistent software documentation for users and developers following Cumulocity standards.
	## Primary Objective {#primary-objective}

[github-actions]

Suggested ID for this heading:

Suggested change

	1. **Clarity First**: Use simple, direct language. Break complex ideas into short sentences. Get to the point fast with key takeaways upfront.
	## Writing Principles {#writing-principles}

[github-actions]

Suggested ID for this heading:

Suggested change

	Use admonitions for:
	### Notes & Callouts {#notes-callouts}

[github-actions]

Suggested ID for this heading:

Suggested change

	- **Data types**: lowercase (boolean, string, integer)
	### Capitalization Rules {#capitalization-rules}

[github-actions]

Suggested ID for this heading:

Suggested change

	- Use shortcodes for Cumulocity terms: {{< company-c8y >}}, {{< product-c8y-iot >}}
	### Variables {#variables}

[github-actions]

Suggested ID for this heading:

Suggested change

	## Content Organization Checklist {#content-organization-checklist}

[github-actions]

Suggested ID for this heading:

Suggested change

	For each piece of content, verify:
	## Quality Check {#quality-check}

[github-actions]

AI Style Suggestions for content/additional-resources/more-resources.md:

Here are the line-specific suggestions based on the Cumulocity Documentation Style Guide:

1. Line 19:
   • Suggestion: Remove the apostrophe in "what's." The phrase should read: "To learn about what is new in {{< product-c8y-iot >}}..." to avoid contractions for clarity and consistency.

This is not a rule we follow. We actually support to use an informal tone: "In general, we write our documentation in an informal tone, so we recommend using common two-word contractions such as you're, don't, and there's." I will add this to the custom instructions.

2. Line 19:
   • Suggestion: "which covers" could be simplified to "cover" for directness. The revised section would read: "...content that covers the new and enhanced functionality..."

This is nonsense as it just changes "which" to "that" which is not a simplification.

3. Line 20:
   • Suggestion: Change "Tech Community {#tech-community}" to "Tech Community {#techcommunity}" as it aligns with the correct format for IDs (no hyphens should be used).

As discussed, we do not want to change existing IDs. We must add this to the custom instructions.

4. Line 43:
   • Suggestion: Change "can be found and subscribed to at:" to "can be found and subscribed to here:" for a more conversational tone.

Could be changed, but really minor.

5. Line 44:
   • Suggestion: For the URL, consider formatting it as a sentence. It could read: "For information on known issues and the next upgrade, subscribe at [http://status.{{< domain-c8y >}}/](http://status.{{< domain-c8y >}}/)."

This changes the content! It misses the first part "For {{< product-c8y-iot >}} cloud shared environments, " and also leaves out "can be found".
But I agree with removing the colon.

6. Line 46:
   • Suggestion: Align the title to the Cumulocity naming convention. Replace "Cloud environments status page {#cloud-environments-status-page}" with "Cloud environments status {#cloud-environments}".

This is nonsense.

7. Line 48:
   • Suggestion: There is duplicate information here, as the text from lines 43-44 is repeated. Remove one of the sections to eliminate redundancy.

This is correct.

By implementing these suggestions, clarity, consistency, and tone across the document will be improved while adhering to the Cumulocity Documentation Style Guide.

[github-actions]

AI Style Suggestions for scripts/copilot-instructions.md:

Here are line-specific suggestions to improve clarity, consistency, and tone based on the Cumulocity Documentation Style Guide:

1. Line 1: Remove the "Cumulocity Documentation Style Guide - Copilot Instructions" heading as it serves no purpose in the provided content.

2. Line 2: Ensure immediate engagement by rephrasing to start with "This document generates clear...".

3. Lines 8, 10: Replace "fast" with "quickly" for a more formal tone.

4. Line 12: Replace "its" with "your". The sentence should read, "Read aloud to check your flow."

5. Line 19: Change "Only" to "only" for consistency in the capitalization format.

6. Line 22: Add "the" to improve clarity. Modify to "capitalize the first word and proper nouns".

7. Line 32: Change "can" in "can, may, might,..." to "avoid using" to follow the style guide more closely.

8. Line 43: Add a colon after "No periods on" to introduce the list.

9. Line 71: Remove "you can..." which detracts from direct command. Begin with "Use inline code..." instead.

10. Line 77: Avoid the use of "click here." Instead, modify to "For details, refer to...".

11. Lines 98-99: Rather than saying "before generating documentation," say "When generating documentation" for clarity.

12. Line 101: "Lead with the most important information" should have "the" added for correctness.

13. Line 106: Ensure that “context” in "Include context before actions" is followed by an explicit example for clarity.

14. Line 110: Rephrasal of "Verify each piece of content" for conciseness is suggested. Change to "For every piece of content, verify:".

15. Lines 111-116: Present each point as complete sentences (e.g., "Can a non-native English speaker understand this?" should be rephrased to "Ensure a non-native English speaker can understand this.") to improve clarity.

Following these suggestions will enhance overall clarity, consistency, and adherence to your documentation style guide.