mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-13 02:41:50 +08:00
feat: add issue discovery view for managing discovery sessions and findings
- Implemented main render function for the issue discovery view. - Added data loading functions to fetch discoveries, details, findings, and progress. - Created rendering functions for discovery list and detail sections. - Introduced filtering and searching capabilities for findings. - Implemented actions for exporting and dismissing findings. - Added polling mechanism to track discovery progress. - Included utility functions for HTML escaping and cleanup.
This commit is contained in:
catlog22
325
.claude/skills/software-manual/specs/html-template.md
Normal file
325
.claude/skills/software-manual/specs/html-template.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# HTML Template Specification
|
||||
|
||||
Technical specification for the TiddlyWiki-style HTML output.
|
||||
|
||||
## Overview
|
||||
|
||||
The output is a single, self-contained HTML file with:
|
||||
- All CSS embedded inline
|
||||
- All JavaScript embedded inline
|
||||
- All images embedded as Base64
|
||||
- Full offline functionality
|
||||
|
||||
## File Structure
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>{{SOFTWARE_NAME}} - User Manual</title>
|
||||
<style>{{EMBEDDED_CSS}}</style>
|
||||
</head>
|
||||
<body class="wiki-container" data-theme="light">
|
||||
<aside class="wiki-sidebar">...</aside>
|
||||
<main class="wiki-content">...</main>
|
||||
<button class="theme-toggle">...</button>
|
||||
<script id="search-index" type="application/json">{{SEARCH_INDEX}}</script>
|
||||
<script>{{EMBEDDED_JS}}</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
## Placeholders
|
||||
|
||||
| Placeholder | Description | Source |
|
||||
|-------------|-------------|--------|
|
||||
| `{{SOFTWARE_NAME}}` | Software name | manual-config.json |
|
||||
| `{{VERSION}}` | Version number | manual-config.json |
|
||||
| `{{EMBEDDED_CSS}}` | All CSS content | wiki-base.css + wiki-dark.css |
|
||||
| `{{TOC_HTML}}` | Table of contents | Generated from sections |
|
||||
| `{{TIDDLERS_HTML}}` | All content blocks | Converted from Markdown |
|
||||
| `{{SEARCH_INDEX_JSON}}` | Search data | Generated from content |
|
||||
| `{{EMBEDDED_JS}}` | JavaScript code | Inline in template |
|
||||
| `{{TIMESTAMP}}` | Generation timestamp | ISO 8601 format |
|
||||
| `{{LOGO_BASE64}}` | Logo image | Project logo or generated |
|
||||
|
||||
## Component Specifications
|
||||
|
||||
### Sidebar (`.wiki-sidebar`)
|
||||
|
||||
```
|
||||
Width: 280px (fixed)
|
||||
Position: Fixed left
|
||||
Height: 100vh
|
||||
Components:
|
||||
- Logo area (.wiki-logo)
|
||||
- Search box (.wiki-search)
|
||||
- Tag navigation (.wiki-tags)
|
||||
- Table of contents (.wiki-toc)
|
||||
```
|
||||
|
||||
### Main Content (`.wiki-content`)
|
||||
|
||||
```
|
||||
Margin-left: 280px (sidebar width)
|
||||
Max-width: 900px (content)
|
||||
Components:
|
||||
- Header bar (.content-header)
|
||||
- Tiddler container (.tiddler-container)
|
||||
- Footer (.wiki-footer)
|
||||
```
|
||||
|
||||
### Tiddler (Content Block)
|
||||
|
||||
```html
|
||||
<article class="tiddler"
|
||||
id="tiddler-{{ID}}"
|
||||
data-tags="{{TAGS}}"
|
||||
data-difficulty="{{DIFFICULTY}}">
|
||||
<header class="tiddler-header">
|
||||
<h2 class="tiddler-title">
|
||||
<button class="collapse-toggle">▼</button>
|
||||
{{TITLE}}
|
||||
</h2>
|
||||
<div class="tiddler-meta">
|
||||
<span class="difficulty-badge {{DIFFICULTY}}">{{DIFFICULTY_LABEL}}</span>
|
||||
{{TAG_BADGES}}
|
||||
</div>
|
||||
</header>
|
||||
<div class="tiddler-content">
|
||||
{{CONTENT_HTML}}
|
||||
</div>
|
||||
</article>
|
||||
```
|
||||
|
||||
### Search Index Format
|
||||
|
||||
```json
|
||||
{
|
||||
"tiddler-overview": {
|
||||
"title": "Product Overview",
|
||||
"body": "Plain text content for searching...",
|
||||
"tags": ["getting-started", "overview"]
|
||||
},
|
||||
"tiddler-ui-guide": {
|
||||
"title": "UI Guide",
|
||||
"body": "Plain text content...",
|
||||
"tags": ["ui-guide"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Interactive Features
|
||||
|
||||
### 1. Search
|
||||
|
||||
- Full-text search with result highlighting
|
||||
- Searches title, body, and tags
|
||||
- Shows up to 10 results
|
||||
- Keyboard accessible (Enter to search, Esc to close)
|
||||
|
||||
### 2. Collapse/Expand
|
||||
|
||||
- Per-section toggle via button
|
||||
- Expand All / Collapse All buttons
|
||||
- State indicated by ▼ (expanded) or ▶ (collapsed)
|
||||
- Smooth transition animation
|
||||
|
||||
### 3. Tag Filtering
|
||||
|
||||
- Tags: all, getting-started, ui-guide, api, config, troubleshooting, examples
|
||||
- Single selection (radio behavior)
|
||||
- "all" shows everything
|
||||
- Hidden tiddlers via `display: none`
|
||||
|
||||
### 4. Theme Toggle
|
||||
|
||||
- Light/Dark mode switch
|
||||
- Persists to localStorage (`wiki-theme`)
|
||||
- Applies to entire document via `[data-theme="dark"]`
|
||||
- Toggle button shows sun/moon icon
|
||||
|
||||
### 5. Responsive Design
|
||||
|
||||
```
|
||||
Breakpoints:
|
||||
- Desktop (> 1024px): Sidebar visible
|
||||
- Tablet (768-1024px): Sidebar collapsible
|
||||
- Mobile (< 768px): Sidebar hidden, hamburger menu
|
||||
```
|
||||
|
||||
### 6. Print Support
|
||||
|
||||
- Hides sidebar, toggles, interactive elements
|
||||
- Expands all collapsed sections
|
||||
- Adjusts colors for print
|
||||
- Page breaks between sections
|
||||
|
||||
## Accessibility
|
||||
|
||||
### Keyboard Navigation
|
||||
|
||||
- Tab through interactive elements
|
||||
- Enter to activate buttons
|
||||
- Escape to close search results
|
||||
- Arrow keys in search results
|
||||
|
||||
### ARIA Attributes
|
||||
|
||||
```html
|
||||
<input aria-label="Search">
|
||||
<nav aria-label="Table of Contents">
|
||||
<button aria-label="Toggle theme">
|
||||
<div aria-live="polite"> <!-- For search results -->
|
||||
```
|
||||
|
||||
### Color Contrast
|
||||
|
||||
- Text/background ratio ≥ 4.5:1
|
||||
- Interactive elements clearly visible
|
||||
- Focus indicators visible
|
||||
|
||||
## Performance
|
||||
|
||||
### Target Metrics
|
||||
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| Total file size | < 10MB |
|
||||
| Time to interactive | < 2s |
|
||||
| Search latency | < 100ms |
|
||||
|
||||
### Optimization Strategies
|
||||
|
||||
1. **Lazy loading for images**: `loading="lazy"`
|
||||
2. **Efficient search**: In-memory index, no external requests
|
||||
3. **CSS containment**: Scope styles to components
|
||||
4. **Minimal JavaScript**: Vanilla JS, no libraries
|
||||
|
||||
## CSS Variables
|
||||
|
||||
### Light Theme
|
||||
|
||||
```css
|
||||
:root {
|
||||
--bg-primary: #ffffff;
|
||||
--bg-secondary: #f8f9fa;
|
||||
--text-primary: #212529;
|
||||
--text-secondary: #495057;
|
||||
--accent-color: #0d6efd;
|
||||
--border-color: #dee2e6;
|
||||
}
|
||||
```
|
||||
|
||||
### Dark Theme
|
||||
|
||||
```css
|
||||
[data-theme="dark"] {
|
||||
--bg-primary: #1a1a2e;
|
||||
--bg-secondary: #16213e;
|
||||
--text-primary: #eaeaea;
|
||||
--text-secondary: #b8b8b8;
|
||||
--accent-color: #4dabf7;
|
||||
--border-color: #2d3748;
|
||||
}
|
||||
```
|
||||
|
||||
## Markdown to HTML Mapping
|
||||
|
||||
| Markdown | HTML |
|
||||
|----------|------|
|
||||
| `# Heading` | `<h1>` |
|
||||
| `## Heading` | `<h2>` |
|
||||
| `**bold**` | `<strong>` |
|
||||
| `*italic*` | `<em>` |
|
||||
| `` `code` `` | `<code>` |
|
||||
| `[link](url)` | `<a href="url">` |
|
||||
| `- item` | `<ul><li>` |
|
||||
| `1. item` | `<ol><li>` |
|
||||
| ``` ```js ``` | `<pre><code class="language-js">` |
|
||||
| `> quote` | `<blockquote>` |
|
||||
| `---` | `<hr>` |
|
||||
|
||||
## Screenshot Embedding
|
||||
|
||||
### Marker Format
|
||||
|
||||
```markdown
|
||||
<!-- SCREENSHOT: id="ss-login" url="/login" description="Login form" -->
|
||||
```
|
||||
|
||||
### Embedded Format
|
||||
|
||||
```html
|
||||
<figure class="screenshot">
|
||||
<img src="data:image/png;base64,{{BASE64_DATA}}"
|
||||
alt="Login form"
|
||||
loading="lazy">
|
||||
<figcaption>Login form</figcaption>
|
||||
</figure>
|
||||
```
|
||||
|
||||
### Placeholder (if missing)
|
||||
|
||||
```html
|
||||
<div class="screenshot-placeholder">
|
||||
[Screenshot: ss-login - Login form]
|
||||
</div>
|
||||
```
|
||||
|
||||
## File Size Optimization
|
||||
|
||||
### CSS
|
||||
|
||||
- Minify before embedding
|
||||
- Remove unused styles
|
||||
- Combine duplicate rules
|
||||
|
||||
### JavaScript
|
||||
|
||||
- Minify before embedding
|
||||
- Remove console.log statements
|
||||
- Use IIFE for scoping
|
||||
|
||||
### Images
|
||||
|
||||
- Compress before Base64 encoding
|
||||
- Use appropriate dimensions (max 1280px width)
|
||||
- Consider WebP format if browser support is acceptable
|
||||
|
||||
## Validation
|
||||
|
||||
### HTML Validation
|
||||
|
||||
- W3C HTML5 compliance
|
||||
- Proper nesting
|
||||
- Required attributes present
|
||||
|
||||
### CSS Validation
|
||||
|
||||
- Valid property values
|
||||
- No deprecated properties
|
||||
- Vendor prefixes where needed
|
||||
|
||||
### JavaScript
|
||||
|
||||
- No syntax errors
|
||||
- All functions defined
|
||||
- Error handling for edge cases
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] Opens in Chrome/Firefox/Safari/Edge
|
||||
- [ ] Search works correctly
|
||||
- [ ] Collapse/expand works
|
||||
- [ ] Tag filtering works
|
||||
- [ ] Theme toggle works
|
||||
- [ ] Print preview correct
|
||||
- [ ] Keyboard navigation works
|
||||
- [ ] Mobile responsive
|
||||
- [ ] Offline functionality
|
||||
- [ ] All links valid
|
||||
- [ ] All images display
|
||||
- [ ] No console errors
|
||||
253
.claude/skills/software-manual/specs/quality-standards.md
Normal file
253
.claude/skills/software-manual/specs/quality-standards.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# Quality Standards
|
||||
|
||||
Quality gates and standards for software manual generation.
|
||||
|
||||
## Quality Dimensions
|
||||
|
||||
### 1. Completeness (25%)
|
||||
|
||||
All required sections present and adequately covered.
|
||||
|
||||
| Requirement | Weight | Criteria |
|
||||
|-------------|--------|----------|
|
||||
| Overview section | 5 | Product intro, features, quick start |
|
||||
| UI Guide | 5 | All major screens documented |
|
||||
| API Reference | 5 | All public APIs documented |
|
||||
| Configuration | 4 | All config options explained |
|
||||
| Troubleshooting | 3 | Common issues addressed |
|
||||
| Examples | 3 | Multi-level examples provided |
|
||||
|
||||
**Scoring**:
|
||||
- 100%: All sections present with adequate depth
|
||||
- 80%: All sections present, some lacking depth
|
||||
- 60%: Missing 1-2 sections
|
||||
- 40%: Missing 3+ sections
|
||||
- 0%: Critical sections missing (overview, UI guide)
|
||||
|
||||
### 2. Consistency (25%)
|
||||
|
||||
Terminology, style, and structure uniform across sections.
|
||||
|
||||
| Aspect | Check |
|
||||
|--------|-------|
|
||||
| Terminology | Same term for same concept throughout |
|
||||
| Formatting | Consistent heading levels, code block styles |
|
||||
| Tone | Consistent formality level |
|
||||
| Cross-references | All internal links valid |
|
||||
| Screenshot naming | Follow `ss-{feature}-{action}` pattern |
|
||||
|
||||
**Scoring**:
|
||||
- 100%: Zero inconsistencies
|
||||
- 80%: 1-3 minor inconsistencies
|
||||
- 60%: 4-6 inconsistencies
|
||||
- 40%: 7-10 inconsistencies
|
||||
- 0%: Pervasive inconsistencies
|
||||
|
||||
### 3. Depth (25%)
|
||||
|
||||
Content provides sufficient detail for target audience.
|
||||
|
||||
| Level | Criteria |
|
||||
|-------|----------|
|
||||
| Shallow | Basic descriptions only |
|
||||
| Standard | Descriptions + usage examples |
|
||||
| Deep | Descriptions + examples + edge cases + best practices |
|
||||
|
||||
**Per-Section Depth Check**:
|
||||
- [ ] Explains "what" (definition)
|
||||
- [ ] Explains "why" (rationale)
|
||||
- [ ] Explains "how" (procedure)
|
||||
- [ ] Provides examples
|
||||
- [ ] Covers edge cases
|
||||
- [ ] Includes tips/best practices
|
||||
|
||||
**Scoring**:
|
||||
- 100%: Deep coverage on all critical sections
|
||||
- 80%: Standard coverage on all sections
|
||||
- 60%: Shallow coverage on some sections
|
||||
- 40%: Missing depth in critical areas
|
||||
- 0%: Superficial throughout
|
||||
|
||||
### 4. Readability (25%)
|
||||
|
||||
Clear, user-friendly writing that's easy to follow.
|
||||
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| Sentence length | Average < 20 words |
|
||||
| Paragraph length | Average < 5 sentences |
|
||||
| Heading hierarchy | Proper H1 > H2 > H3 nesting |
|
||||
| Code blocks | Language specified |
|
||||
| Lists | Used for 3+ items |
|
||||
| Screenshots | Placed near relevant text |
|
||||
|
||||
**Structural Elements**:
|
||||
- [ ] Clear section headers
|
||||
- [ ] Numbered steps for procedures
|
||||
- [ ] Bullet lists for options/features
|
||||
- [ ] Tables for comparisons
|
||||
- [ ] Code blocks with syntax highlighting
|
||||
- [ ] Screenshots with captions
|
||||
|
||||
**Scoring**:
|
||||
- 100%: All readability criteria met
|
||||
- 80%: Minor structural issues
|
||||
- 60%: Some sections hard to follow
|
||||
- 40%: Significant readability problems
|
||||
- 0%: Unclear, poorly structured
|
||||
|
||||
## Overall Quality Score
|
||||
|
||||
```
|
||||
Overall = (Completeness × 0.25) + (Consistency × 0.25) +
|
||||
(Depth × 0.25) + (Readability × 0.25)
|
||||
```
|
||||
|
||||
**Quality Gates**:
|
||||
|
||||
| Gate | Threshold | Action |
|
||||
|------|-----------|--------|
|
||||
| Pass | ≥ 80% | Proceed to HTML generation |
|
||||
| Review | 60-79% | Address warnings, proceed with caution |
|
||||
| Fail | < 60% | Must address errors before continuing |
|
||||
|
||||
## Issue Classification
|
||||
|
||||
### Errors (Must Fix)
|
||||
|
||||
- Missing required sections
|
||||
- Invalid cross-references
|
||||
- Broken screenshot markers
|
||||
- Code blocks without language
|
||||
- Incomplete procedures (missing steps)
|
||||
|
||||
### Warnings (Should Fix)
|
||||
|
||||
- Terminology inconsistencies
|
||||
- Sections lacking depth
|
||||
- Missing examples
|
||||
- Long paragraphs (> 7 sentences)
|
||||
- Screenshots missing captions
|
||||
|
||||
### Info (Nice to Have)
|
||||
|
||||
- Optimization suggestions
|
||||
- Additional example opportunities
|
||||
- Alternative explanations
|
||||
- Enhancement ideas
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
### Pre-Generation
|
||||
|
||||
- [ ] All agents completed successfully
|
||||
- [ ] No errors in consolidation report
|
||||
- [ ] Overall score ≥ 60%
|
||||
|
||||
### Post-Generation
|
||||
|
||||
- [ ] HTML renders correctly
|
||||
- [ ] Search returns relevant results
|
||||
- [ ] All screenshots display
|
||||
- [ ] Theme toggle works
|
||||
- [ ] Print preview looks good
|
||||
|
||||
### Final Review
|
||||
|
||||
- [ ] User previewed and approved
|
||||
- [ ] File size reasonable (< 10MB)
|
||||
- [ ] No console errors in browser
|
||||
- [ ] Accessible (keyboard navigation works)
|
||||
|
||||
## Automated Checks
|
||||
|
||||
```javascript
|
||||
function runQualityChecks(workDir) {
|
||||
const results = {
|
||||
completeness: checkCompleteness(workDir),
|
||||
consistency: checkConsistency(workDir),
|
||||
depth: checkDepth(workDir),
|
||||
readability: checkReadability(workDir)
|
||||
};
|
||||
|
||||
results.overall = (
|
||||
results.completeness * 0.25 +
|
||||
results.consistency * 0.25 +
|
||||
results.depth * 0.25 +
|
||||
results.readability * 0.25
|
||||
);
|
||||
|
||||
return results;
|
||||
}
|
||||
|
||||
function checkCompleteness(workDir) {
|
||||
const requiredSections = [
|
||||
'section-overview.md',
|
||||
'section-ui-guide.md',
|
||||
'section-api-reference.md',
|
||||
'section-configuration.md',
|
||||
'section-troubleshooting.md',
|
||||
'section-examples.md'
|
||||
];
|
||||
|
||||
const existing = Glob(`${workDir}/sections/section-*.md`);
|
||||
const found = requiredSections.filter(s =>
|
||||
existing.some(e => e.endsWith(s))
|
||||
);
|
||||
|
||||
return (found.length / requiredSections.length) * 100;
|
||||
}
|
||||
|
||||
function checkConsistency(workDir) {
|
||||
// Check terminology, cross-references, naming conventions
|
||||
const issues = [];
|
||||
|
||||
// ... implementation ...
|
||||
|
||||
return Math.max(0, 100 - issues.length * 10);
|
||||
}
|
||||
|
||||
function checkDepth(workDir) {
|
||||
// Check content length, examples, edge cases
|
||||
const sections = Glob(`${workDir}/sections/section-*.md`);
|
||||
let totalScore = 0;
|
||||
|
||||
for (const section of sections) {
|
||||
const content = Read(section);
|
||||
let sectionScore = 0;
|
||||
|
||||
if (content.length > 500) sectionScore += 20;
|
||||
if (content.includes('```')) sectionScore += 20;
|
||||
if (content.includes('Example')) sectionScore += 20;
|
||||
if (content.match(/\d+\./g)?.length > 3) sectionScore += 20;
|
||||
if (content.includes('Note:') || content.includes('Tip:')) sectionScore += 20;
|
||||
|
||||
totalScore += sectionScore;
|
||||
}
|
||||
|
||||
return totalScore / sections.length;
|
||||
}
|
||||
|
||||
function checkReadability(workDir) {
|
||||
// Check structure, formatting, organization
|
||||
const sections = Glob(`${workDir}/sections/section-*.md`);
|
||||
let issues = 0;
|
||||
|
||||
for (const section of sections) {
|
||||
const content = Read(section);
|
||||
|
||||
// Check heading hierarchy
|
||||
if (!content.startsWith('# ')) issues++;
|
||||
|
||||
// Check code block languages
|
||||
const codeBlocks = content.match(/```\w*/g);
|
||||
if (codeBlocks?.some(b => b === '```')) issues++;
|
||||
|
||||
// Check paragraph length
|
||||
const paragraphs = content.split('\n\n');
|
||||
if (paragraphs.some(p => p.split('. ').length > 7)) issues++;
|
||||
}
|
||||
|
||||
return Math.max(0, 100 - issues * 10);
|
||||
}
|
||||
```
|
||||
298
.claude/skills/software-manual/specs/writing-style.md
Normal file
298
.claude/skills/software-manual/specs/writing-style.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# Writing Style Guide
|
||||
|
||||
User-friendly writing standards for software manuals.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. User-Centered
|
||||
|
||||
Write for the user, not the developer.
|
||||
|
||||
**Do**:
|
||||
- "Click the **Save** button to save your changes"
|
||||
- "Enter your email address in the login form"
|
||||
|
||||
**Don't**:
|
||||
- "The onClick handler triggers the save mutation"
|
||||
- "POST to /api/auth/login with email in body"
|
||||
|
||||
### 2. Action-Oriented
|
||||
|
||||
Focus on what users can **do**, not what the system does.
|
||||
|
||||
**Do**:
|
||||
- "You can export your data as CSV"
|
||||
- "To create a new project, click **New Project**"
|
||||
|
||||
**Don't**:
|
||||
- "The system exports data in CSV format"
|
||||
- "A new project is created when the button is clicked"
|
||||
|
||||
### 3. Clear and Direct
|
||||
|
||||
Use simple, straightforward language.
|
||||
|
||||
**Do**:
|
||||
- "Select a file to upload"
|
||||
- "The maximum file size is 10MB"
|
||||
|
||||
**Don't**:
|
||||
- "Utilize the file selection interface to designate a file for uploading"
|
||||
- "File size constraints limit uploads to 10 megabytes"
|
||||
|
||||
## Tone
|
||||
|
||||
### Friendly but Professional
|
||||
|
||||
- Conversational but not casual
|
||||
- Helpful but not condescending
|
||||
- Confident but not arrogant
|
||||
|
||||
**Examples**:
|
||||
|
||||
| Too Casual | Just Right | Too Formal |
|
||||
|------------|------------|------------|
|
||||
| "Yo, here's how..." | "Here's how to..." | "The following procedure describes..." |
|
||||
| "Easy peasy!" | "That's all you need to do." | "The procedure has been completed." |
|
||||
| "Don't worry about it" | "You don't need to change this" | "This parameter does not require modification" |
|
||||
|
||||
### Second Person
|
||||
|
||||
Address the user directly as "you".
|
||||
|
||||
**Do**: "You can customize your dashboard..."
|
||||
**Don't**: "Users can customize their dashboards..."
|
||||
|
||||
## Structure
|
||||
|
||||
### Headings
|
||||
|
||||
Use clear, descriptive headings that tell users what they'll learn.
|
||||
|
||||
**Good Headings**:
|
||||
- "Getting Started"
|
||||
- "Creating Your First Project"
|
||||
- "Configuring Email Notifications"
|
||||
- "Troubleshooting Login Issues"
|
||||
|
||||
**Weak Headings**:
|
||||
- "Overview"
|
||||
- "Step 1"
|
||||
- "Settings"
|
||||
- "FAQ"
|
||||
|
||||
### Procedures
|
||||
|
||||
Number steps for sequential tasks.
|
||||
|
||||
```markdown
|
||||
## Creating a New User
|
||||
|
||||
1. Navigate to **Settings** > **Users**.
|
||||
2. Click the **Add User** button.
|
||||
3. Enter the user's email address.
|
||||
4. Select a role from the dropdown.
|
||||
5. Click **Save**.
|
||||
|
||||
The new user will receive an invitation email.
|
||||
```
|
||||
|
||||
### Features/Options
|
||||
|
||||
Use bullet lists for non-sequential items.
|
||||
|
||||
```markdown
|
||||
## Export Options
|
||||
|
||||
You can export your data in several formats:
|
||||
|
||||
- **CSV**: Compatible with spreadsheets
|
||||
- **JSON**: Best for developers
|
||||
- **PDF**: Ideal for sharing reports
|
||||
```
|
||||
|
||||
### Comparisons
|
||||
|
||||
Use tables for comparing options.
|
||||
|
||||
```markdown
|
||||
## Plan Comparison
|
||||
|
||||
| Feature | Free | Pro | Enterprise |
|
||||
|---------|------|-----|------------|
|
||||
| Projects | 3 | Unlimited | Unlimited |
|
||||
| Storage | 1GB | 10GB | 100GB |
|
||||
| Support | Community | Email | Dedicated |
|
||||
```
|
||||
|
||||
## Content Types
|
||||
|
||||
### Conceptual (What Is)
|
||||
|
||||
Explain what something is and why it matters.
|
||||
|
||||
```markdown
|
||||
## What is a Workspace?
|
||||
|
||||
A workspace is a container for your projects and team members. Each workspace
|
||||
has its own settings, billing, and permissions. You might create separate
|
||||
workspaces for different clients or departments.
|
||||
```
|
||||
|
||||
### Procedural (How To)
|
||||
|
||||
Step-by-step instructions for completing a task.
|
||||
|
||||
```markdown
|
||||
## How to Create a Workspace
|
||||
|
||||
1. Click your profile icon in the top-right corner.
|
||||
2. Select **Create Workspace**.
|
||||
3. Enter a name for your workspace.
|
||||
4. Choose a plan (you can upgrade later).
|
||||
5. Click **Create**.
|
||||
|
||||
Your new workspace is ready to use.
|
||||
```
|
||||
|
||||
### Reference (API/Config)
|
||||
|
||||
Detailed specifications and parameters.
|
||||
|
||||
```markdown
|
||||
## Configuration Options
|
||||
|
||||
### `DATABASE_URL`
|
||||
|
||||
- **Type**: String (required)
|
||||
- **Format**: `postgresql://user:password@host:port/database`
|
||||
- **Example**: `postgresql://admin:secret@localhost:5432/myapp`
|
||||
|
||||
Database connection string for PostgreSQL.
|
||||
```
|
||||
|
||||
## Formatting
|
||||
|
||||
### Bold
|
||||
|
||||
Use for:
|
||||
- UI elements: Click **Save**
|
||||
- First use of key terms: **Workspaces** contain projects
|
||||
- Emphasis: **Never** share your API key
|
||||
|
||||
### Italic
|
||||
|
||||
Use for:
|
||||
- Introducing new terms: A *workspace* is...
|
||||
- Placeholders: Replace *your-api-key* with...
|
||||
- Emphasis (sparingly): This is *really* important
|
||||
|
||||
### Code
|
||||
|
||||
Use for:
|
||||
- Commands: Run `npm install`
|
||||
- File paths: Edit `config/settings.json`
|
||||
- Environment variables: Set `DATABASE_URL`
|
||||
- API endpoints: POST `/api/users`
|
||||
- Code references: The `handleSubmit` function
|
||||
|
||||
### Code Blocks
|
||||
|
||||
Always specify the language.
|
||||
|
||||
```javascript
|
||||
// Example: Fetching user data
|
||||
const response = await fetch('/api/user');
|
||||
const user = await response.json();
|
||||
```
|
||||
|
||||
### Notes and Warnings
|
||||
|
||||
Use for important callouts.
|
||||
|
||||
```markdown
|
||||
> **Note**: This feature requires a Pro plan.
|
||||
|
||||
> **Warning**: Deleting a workspace cannot be undone.
|
||||
|
||||
> **Tip**: Use keyboard shortcuts to work faster.
|
||||
```
|
||||
|
||||
## Screenshots
|
||||
|
||||
### When to Include
|
||||
|
||||
- First time showing a UI element
|
||||
- Complex interfaces
|
||||
- Before/after comparisons
|
||||
- Error states
|
||||
|
||||
### Guidelines
|
||||
|
||||
- Capture just the relevant area
|
||||
- Use consistent dimensions
|
||||
- Highlight important elements
|
||||
- Add descriptive captions
|
||||
|
||||
```markdown
|
||||
<!-- SCREENSHOT: id="ss-dashboard" description="Main dashboard showing project list" -->
|
||||
|
||||
*The dashboard displays all your projects with their status.*
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Good Section Example
|
||||
|
||||
```markdown
|
||||
## Inviting Team Members
|
||||
|
||||
You can invite colleagues to collaborate on your projects.
|
||||
|
||||
### To invite a team member:
|
||||
|
||||
1. Open **Settings** > **Team**.
|
||||
2. Click **Invite Member**.
|
||||
3. Enter their email address.
|
||||
4. Select their role:
|
||||
- **Admin**: Full access to all settings
|
||||
- **Editor**: Can edit projects
|
||||
- **Viewer**: Read-only access
|
||||
5. Click **Send Invite**.
|
||||
|
||||
The person will receive an email with a link to join your workspace.
|
||||
|
||||
> **Note**: You can have up to 5 team members on the Free plan.
|
||||
|
||||
<!-- SCREENSHOT: id="ss-invite-team" description="Team invitation dialog" -->
|
||||
```
|
||||
|
||||
## Language Guidelines
|
||||
|
||||
### Avoid Jargon
|
||||
|
||||
| Technical | User-Friendly |
|
||||
|-----------|---------------|
|
||||
| Execute | Run |
|
||||
| Terminate | Stop, End |
|
||||
| Instantiate | Create |
|
||||
| Invoke | Call, Use |
|
||||
| Parameterize | Set, Configure |
|
||||
| Persist | Save |
|
||||
|
||||
### Be Specific
|
||||
|
||||
| Vague | Specific |
|
||||
|-------|----------|
|
||||
| "Click the button" | "Click **Save**" |
|
||||
| "Enter information" | "Enter your email address" |
|
||||
| "An error occurred" | "Your password must be at least 8 characters" |
|
||||
| "It takes a moment" | "This typically takes 2-3 seconds" |
|
||||
|
||||
### Use Active Voice
|
||||
|
||||
| Passive | Active |
|
||||
|---------|--------|
|
||||
| "The file is uploaded" | "Upload the file" |
|
||||
| "Settings are saved" | "Click **Save** to keep your changes" |
|
||||
| "Errors are displayed" | "The form shows any errors" |
|
||||
Reference in New Issue
Block a user