|
| 1 | +--- |
| 2 | +applyTo: '.github/copilot-instructions.md, .github/instructions/*.instructions.md, decisions/**/*.md' |
| 3 | + |
| 4 | +description: 'This file contains instructions for wording and writing style. |
| 5 | + It includes guidelines for creating and modifying instruction files, decision documents, and Copilot instructions. |
| 6 | + Ensure to follow the practices outlined in this file to maintain consistency and clarity in documentation.' |
| 7 | +--- |
| 8 | + |
| 9 | +# Wording and Writing Style Instructions |
| 10 | + |
| 11 | +## General Style |
| 12 | + |
| 13 | +* MUST use clear, concise, and direct language. |
| 14 | +* MUST maintain a consistent formal, professional tone throughout all documentation. |
| 15 | +* MUST use active voice rather than passive voice (e.g., "Use this pattern" instead of "This pattern should be used"). |
| 16 | +* MUST use present tense for instructions and guidelines. |
| 17 | +* MUST format headings using Title Case. |
| 18 | +* MUST format all documentation in proper Markdown. |
| 19 | + |
| 20 | +## Directive Language |
| 21 | + |
| 22 | +* MUST use modal verbs to indicate requirements clearly: |
| 23 | + - **MUST**: Required, mandatory action or rule |
| 24 | + - **SHOULD**: Recommended action but not mandatory |
| 25 | + - **MAY**: Optional action |
| 26 | + - **MUST NOT** or **MUST NEVER**: Prohibited action |
| 27 | +* MUST place the directive at the beginning of the bullet point or sentence. |
| 28 | +* MUST maintain consistent formatting of directives (all caps). |
| 29 | + |
| 30 | +## Instruction Files |
| 31 | + |
| 32 | +* MUST include a YAML frontmatter section with `applyTo` and `description` fields. |
| 33 | +* MUST organize content under clear, hierarchical headings. |
| 34 | +* MUST use bullet points for individual instructions within each section. |
| 35 | +* MUST provide concrete examples where appropriate. |
| 36 | +* MUST use code formatting (backticks) for code, file names, and technical terms. |
| 37 | +* MUST include both general principles and specific implementation details. |
| 38 | + |
| 39 | +## Decision Documents |
| 40 | + |
| 41 | +* MUST follow the established ADR (Architecture Decision Record) format. |
| 42 | +* MUST include all required frontmatter fields: authors, applyTo, created, lastModified, state. |
| 43 | +* MUST provide clear context and problem statements. |
| 44 | +* MUST explicitly state the decision and its implications. |
| 45 | +* MUST use consistent terminology when referring to technical concepts. |
| 46 | + |
| 47 | +## Copilot Instructions |
| 48 | + |
| 49 | +* MUST structure guidance as imperative statements. |
| 50 | +* MUST group related instructions under appropriate section headings. |
| 51 | +* MUST explicitly state constraints and limitations. |
| 52 | +* MUST reference specific file paths, folders, or patterns when applicable. |
| 53 | +* MUST include cross-references to related decisions or instruction files when appropriate. |
| 54 | + |
| 55 | +## Examples and References |
| 56 | + |
| 57 | +* MUST use code blocks with appropriate language specifiers for code examples. |
| 58 | +* MUST use relative links when referencing other documents within the repository. |
| 59 | +* SHOULD include brief explanatory comments for complex code examples. |
| 60 | +* SHOULD provide references to external resources when applicable. |
| 61 | + |
| 62 | +## Formatting Conventions |
| 63 | + |
| 64 | +* MUST use a single blank line to separate paragraphs. |
| 65 | +* MUST use a single blank line before and after lists, code blocks, and headings. |
| 66 | +* MUST use consistent indentation (2 spaces) for nested list items. |
| 67 | +* MUST use consistent bullet point symbols (* for primary bullets, - for secondary). |
| 68 | +* MUST use proper nesting of headings (H1 for title, H2 for major sections, H3 for subsections). |
0 commit comments