mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-14 02:42:04 +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:
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