|
1 | 1 | --- |
2 | | -globs: docs/**/*.{md,mdx} |
3 | | -description: Standards for writing and maintaining Continue Docs |
| 2 | +globs: docs/\*_/_.{md,mdx} |
| 3 | +description: This style guide should be used as a reference for maintaining consistency across all Continue documentation |
| 4 | +alwaysApply: false |
4 | 5 | --- |
5 | 6 |
|
6 | | -# Continue Docs Standards |
| 7 | +# Continue Documentation Style Guide |
| 8 | + |
| 9 | +## Overview |
| 10 | + |
| 11 | +## Writing Tone & Voice |
| 12 | + |
| 13 | +### Conversational and Direct |
7 | 14 |
|
8 | 15 | - Follow Docusaurus documentation standards |
9 | | -- Include YAML frontmatter with title, description, and keywords |
10 | | -- Use consistent heading hierarchy starting with h2 (##) |
11 | | -- Include relevant Admonition components for tips, warnings, and info |
12 | | -- Use descriptive alt text for images |
13 | | -- Include cross-references to related documentation |
14 | | -- Reference other docs with relative paths |
| 16 | +- Use simple, conversational language that gets straight to the point |
| 17 | +- Avoid overly technical jargon when simpler terms work |
| 18 | +- Write as if speaking directly to the developer using the tool |
15 | 19 | - Keep paragraphs concise and scannable |
16 | | -- Use code blocks with appropriate language tags |
| 20 | + |
| 21 | +**Example:** |
| 22 | +✅ "You send it a question, and it replies with an answer" |
| 23 | +❌ "The system processes user queries and generates corresponding responses" |
| 24 | + |
| 25 | +### Helpful and Instructional |
| 26 | + |
| 27 | +- Focus on helping users accomplish their goals |
| 28 | +- Use active voice and imperative mood for instructions |
| 29 | +- Assume users want to get things done quickly |
| 30 | +- Include relevant Admonition components for tips, warnings, and info |
| 31 | + |
| 32 | +**Example:** |
| 33 | +✅ "Press cmd/ctrl + L to begin a new session" |
| 34 | +❌ "A new session can be initiated by pressing cmd/ctrl + L" |
| 35 | + |
| 36 | +### Practical and Task-Oriented |
| 37 | + |
| 38 | +- Emphasize what users can accomplish with each feature |
| 39 | +- Lead with benefits and use cases before diving into mechanics |
| 40 | +- Keep explanations grounded in real-world scenarios |
| 41 | + |
| 42 | +## Content Structure |
| 43 | + |
| 44 | +### Page Organization |
| 45 | + |
| 46 | +1. **Visual Introduction**: Lead with GIFs or images showing the feature in action |
| 47 | +2. **Purpose Statement**: Brief explanation of what the feature does and when to use it |
| 48 | +3. **Step-by-Step Instructions**: Clear, actionable steps with keyboard shortcuts |
| 49 | +4. **Platform-Specific Notes**: Separate sections for VS Code and JetBrains when needed |
| 50 | +5. **Additional Tips**: Advanced usage or troubleshooting notes |
| 51 | + |
| 52 | +### Section Headers |
| 53 | + |
| 54 | +- Use consistent heading hierarchy starting with h2 (##) |
| 55 | +- Include YAML frontmatter with title, description, and keywords |
| 56 | +- Use action-oriented headers that describe what users will do |
| 57 | +- Format: "Verb + object" (e.g., "Type a request and press enter") |
| 58 | +- Keep headers concise but descriptive |
| 59 | +- Use title case |
| 60 | + |
| 61 | +**Examples:** |
| 62 | +✅ "Highlight code and activate" |
| 63 | +✅ "Accept or reject changes" |
| 64 | +✅ "Switch between different models" |
| 65 | + |
| 66 | +### Lists and Steps |
| 67 | + |
| 68 | +- Use numbered lists for sequential steps |
| 69 | +- Use bullet points for feature lists or options |
| 70 | +- Keep list items parallel in structure |
| 71 | +- Start action items with verbs |
| 72 | + |
| 73 | +## Technical Writing Standards |
| 74 | + |
| 75 | +### Code and Keyboard Shortcuts |
| 76 | + |
| 77 | +- Use `backticks` for inline code elements |
| 78 | +- Format keyboard shortcuts consistently: `cmd/ctrl + L` |
| 79 | +- Always provide shortcuts for Mac/Windows/Linux |
| 80 | +- Use code blocks for configuration examples with proper syntax highlighting |
| 81 | + |
| 82 | +### Cross-References |
| 83 | + |
| 84 | +- Link to related sections using descriptive anchor text |
| 85 | +- Use relative links to other documentation pages |
| 86 | +- Format: `[descriptive text](/path/to/page)` |
| 87 | + |
| 88 | +### Platform Differences |
| 89 | + |
| 90 | +- Always address both VS Code and JetBrains when applicable |
| 91 | +- Use clear subheadings to separate platform-specific instructions |
| 92 | +- Lead with the more common platform (typically VS Code) when both are covered |
| 93 | + |
| 94 | +## Language Conventions |
| 95 | + |
| 96 | +### Terminology |
| 97 | + |
| 98 | +- **Consistent Terms**: Use the same terms throughout (e.g., "LLM" not "AI model" in some places) |
| 99 | +- **Product Names**: Capitalize product names correctly (VS Code, JetBrains, Continue) |
| 100 | +- **Feature Names**: Use consistent capitalization for Continue features (Chat, Edit, Agent, Autocomplete) |
| 101 | + |
| 102 | +### Abbreviations |
| 103 | + |
| 104 | +- Spell out acronyms on first use, then use abbreviation consistently |
| 105 | +- Common abbreviations: LLM, IDE, API, URL |
| 106 | + |
| 107 | +### Pronouns |
| 108 | + |
| 109 | +- Use "you" to address the user directly |
| 110 | +- Use "it" to refer to the tool/model |
| 111 | +- Avoid "we" unless referring to the Continue team |
0 commit comments