From b836d25e79dd54205bb72f5997186bb01a6b049a Mon Sep 17 00:00:00 2001 From: Arthur Date: Tue, 8 Jul 2025 17:27:47 +0200 Subject: [PATCH] tooling: add prompts to vscode (#23030) --- .../instructions/styleguide-instructions.md | 111 ++++++++++++++++++ .github/prompts/freshness-tier1.prompt.md | 16 +++ .github/prompts/freshness-tier2.prompt.md | 22 ++++ .github/prompts/review.prompt.md | 7 ++ 4 files changed, 156 insertions(+) create mode 100644 .github/instructions/styleguide-instructions.md create mode 100644 .github/prompts/freshness-tier1.prompt.md create mode 100644 .github/prompts/freshness-tier2.prompt.md create mode 100644 .github/prompts/review.prompt.md diff --git a/.github/instructions/styleguide-instructions.md b/.github/instructions/styleguide-instructions.md new file mode 100644 index 0000000000..3e71939247 --- /dev/null +++ b/.github/instructions/styleguide-instructions.md @@ -0,0 +1,111 @@ +--- +applyTo: '**/*.md' +--- +# Documentation Writing Instructions + +These are our documentation writing style guidelines. + +## General Style tips + +* Get to the point fast. +* Talk like a person. +* Simpler is better. +* Be brief. Give customers just enough information to make decisions confidently. Prune every excess word. +* We use Hugo to generate our docs. + +## Grammar + +* Use present tense verbs (is, open) instead of past tense (was, opened). +* Write factual statements and direct commands. Avoid hypotheticals like "could" or "would". +* Use active voice where the subject performs the action. +* Write in second person (you) to speak directly to readers. +* Use gender-neutral language. +* Avoid multiple -ing words that can create ambiguity. +* Keep prepositional phrases simple and clear. +* Place modifiers close to what they modify. + +## Capitalization + +* Use sentence-style capitalization for everything except proper nouns. +* Always capitalize proper nouns. +* Don’t capitalize the spelled-out form of an acronym unless it's a proper noun. +* In programming languages, follow the traditional capitalization of keywords and other special terms. +* Don't use all uppercase for emphasis. + +## Numbers + +* Spell out numbers for zero through nine, unless space is limited. Use numerals for 10 and above. +* Spell out numbers at the beginning of a sentence. +* Spell out ordinal numbers such as first, second, and third. Don't add -ly to form adverbs from ordinal numbers. + +## Punctuation + +* Use short, simple sentences. +* End all sentences with a period. +* Use one space after punctuation marks. +* After a colon, capitalize only proper nouns. +* Avoid semicolons - use separate sentences instead. +* Use question marks sparingly. +* Don't use slashes (/) - use "or" instead. + +## Text formatting + +* UI elements, like menu items, dialog names, and names of text boxes, should be in bold text. +* Use code style for: + * Code elements, like method names, property names, and language keywords. + * SQL commands. + * Command-line commands. + * Database table and column names. + * Resource names (like virtual machine names) that shouldn't be localized. + * URLs that you don't want to be selectable. +* For code placeholders, if you want users to replace part of an input string with their own values, use angle brackets (less than < and greater than > characters) on that placeholder text. +* Don't apply an inline style like italic, bold, or inline code style to headings. + +## Alerts + +* Alerts are a Markdown extension to create block quotes that render with colors and icons that indicate the significance of the content. The following alert types are supported: + + * `[!NOTE]` Information the user should notice even if skimming. + * `[!TIP]` Optional information to help a user be more successful. + * `[!IMPORTANT]` Essential information required for user success. + * `[!CAUTION]` Negative potential consequences of an action. + * `[!WARNING]` Dangerous certain consequences of an action. + +## Links + +* Links to other documentation articles should be relative, not absolute. Include the `.md` suffix. +* Links to bookmarks within the same article should be relative and start with `#`. +* Link descriptions should be descriptive and make sense on their own. Don't use "click here" or "this link" or "here". + +## Images + +* Use images only when they add value. +* Images have a descriptive and meaningful alt text that starts with "Screenshot showing" and ends with ".". +* Videos have a descriptive and meaningful alt text or title that starts with "Video showing" and ends with ".". + +## Numbered steps + +* Write complete sentences with capitalization and periods +* Use imperative verbs +* Clearly indicate where actions take place (UI location) +* For single steps, use a bullet instead of a number +* When allowed, use angle brackets for menu sequences (File > Open) +* When writing ordered lists, only use 1's. + +## Terminology + +* Use "Select" instead of "Click" for UI elements like buttons, menu items, links, dropdowns, and checkboxes. +* Use "might" instead of "may" for conditional statements. +* Avoid latin abbreviations like "e.g.". Use "for example" instead. +* Use the verb "to enable" instead "to allow" unless you're referring to permissions. +* Follow the terms and capitalization guidelines in #fetch [VS Code docs wiki](https://github.com/microsoft/vscode-docs/wiki/VS-Code-glossary) + + +## Complete style guide + +Find all the details of the style guide in these files: + +- `./content/contribute/style/grammar.md` – Grammar rules +- `./content/contribute/style/formatting.md` – Formatting rules +- `./content/contribute/style/recommended-words.md` – Approved words and phrasing +- `./content/contribute/style/voice-tone.md` – Voice and tone guidance diff --git a/.github/prompts/freshness-tier1.prompt.md b/.github/prompts/freshness-tier1.prompt.md new file mode 100644 index 0000000000..a26490a177 --- /dev/null +++ b/.github/prompts/freshness-tier1.prompt.md @@ -0,0 +1,16 @@ +--- +mode: 'edit' +--- + +Imagine you're an experienced technical writer. You need to review content for +how fresh and up to date it is. Apply the following: + +1. Fix spelling errors and typos +2. Verify whether the markdown structure conforms to common markdown standards +3. Ensure the content follows our [style guide file](../instructions/styleguide-instructions.md) as a guide. +4. Make sure the titles on the page provide better context about the content (for an improved search experience). +5. Ensure all the components formatted correctly. +6. Improve the SEO keywords. +7. If you find numbered lists, make sure their numbering only uses 1's. + +Do your best and don't be lazy. \ No newline at end of file diff --git a/.github/prompts/freshness-tier2.prompt.md b/.github/prompts/freshness-tier2.prompt.md new file mode 100644 index 0000000000..e2935f12e4 --- /dev/null +++ b/.github/prompts/freshness-tier2.prompt.md @@ -0,0 +1,22 @@ +--- +mode: 'edit' +--- + +Imagine you're an experienced technical writer. You need to review content for +how fresh and up to date it is. Apply the following: + +1. Improve the presentational layer - components, splitting up the page into smaller pages + Consider the following: + + 1. Can you use tabs to display multiple variants of the same steps? + 2. Can you make a key item of information stand out with a call-out? + 3. Can you reduce a large amount of text to a series of bullet points? + 4. Are there other code components you could use? +2. Check if any operating systems or package versions mentioned are still current and supported +3. Check the accuracy of the content +4. If appropriate, follow the document from start to finish to see if steps make sense in sequence +5. Try to add some helpful next steps to the end of the document, but only if there are no *Next steps* or *Related pages* section, already. +6. Try to clarify, shorten or improve the efficiency of some sentences. +7. Check for LLM readibility. + +Do your best and don't be lazy. \ No newline at end of file diff --git a/.github/prompts/review.prompt.md b/.github/prompts/review.prompt.md new file mode 100644 index 0000000000..47a39e8e14 --- /dev/null +++ b/.github/prompts/review.prompt.md @@ -0,0 +1,7 @@ +--- +mode: edit +description: You are a technical writer reviewing an article for clarity, conciseness, and adherence to the documentation writing style guidelines. +--- +Review the article for clarity, conciseness, and adherence to our documentation [style guidelines](../instructions/styleguide-instructions.md). + +Provide concrete and practical suggestions for improvement.