firefrost-gaming/skill-seekers-reference
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: complete documentation overhaul with v3.1.0 release notes and zh-CN translations

Browse Source 
Documentation restructure:
- New docs/getting-started/ guide (4 files: install, quick-start, first-skill, next-steps)
- New docs/user-guide/ section (6 files: core concepts through troubleshooting)
- New docs/reference/ section (CLI_REFERENCE, CONFIG_FORMAT, ENVIRONMENT_VARIABLES, MCP_REFERENCE)
- New docs/advanced/ section (custom-workflows, mcp-server, multi-source)
- New docs/ARCHITECTURE.md - system architecture overview
- Archived legacy files (QUICKSTART.md, QUICK_REFERENCE.md, docs/guides/USAGE.md) to docs/archive/legacy/

Chinese (zh-CN) translations:
- Full zh-CN mirror of all user-facing docs (getting-started, user-guide, reference, advanced)
- GitHub Actions workflow for translation sync (.github/workflows/translate-docs.yml)
- Translation sync checker script (scripts/check_translation_sync.sh)
- Translation helper script (scripts/translate_doc.py)

Content updates:
- CHANGELOG.md: [Unreleased] → [3.1.0] - 2026-02-22
- README.md: updated with new doc structure links
- AGENTS.md: updated agent documentation
- docs/features/UNIFIED_SCRAPING.md: updated for unified scraper workflow JSON config

Analysis/planning artifacts (kept for reference):
- DOCUMENTATION_OVERHAUL_PLAN.md, DOCUMENTATION_OVERHAUL_SUMMARY.md
- FEATURE_GAP_ANALYSIS.md, IMPLEMENTATION_GAPS_ANALYSIS.md, CREATE_COMMAND_COVERAGE_ANALYSIS.md
- CHINESE_TRANSLATION_IMPLEMENTATION_SUMMARY.md, ISSUE_260_UPDATE.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
yusyus
2026-02-22 01:01:51 +03:00
parent 22bdd4f5f6
commit ba9a8ff8b5
69 changed files with 31304 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

263
docs/ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,263 @@
# Documentation Architecture
> **How Skill Seekers documentation is organized**
---
## Philosophy
Our documentation follows these principles:
1. **Progressive Disclosure** - Start simple, add complexity as needed
2. **Task-Oriented** - Organized by what users want to do
3. **Single Source of Truth** - One authoritative reference per topic
4. **Version Current** - Always reflect the latest release
---
## Directory Structure
```
docs/
├── README.md # Entry point - navigation hub
├── ARCHITECTURE.md # This file
│
├── getting-started/ # New users (lowest cognitive load)
│ ├── 01-installation.md
│ ├── 02-quick-start.md
│ ├── 03-your-first-skill.md
│ └── 04-next-steps.md
│
├── user-guide/ # Common tasks (practical focus)
│ ├── 01-core-concepts.md
│ ├── 02-scraping.md
│ ├── 03-enhancement.md
│ ├── 04-packaging.md
│ ├── 05-workflows.md
│ └── 06-troubleshooting.md
│
├── reference/ # Technical details (comprehensive)
│ ├── CLI_REFERENCE.md
│ ├── MCP_REFERENCE.md
│ ├── CONFIG_FORMAT.md
│ └── ENVIRONMENT_VARIABLES.md
│
└── advanced/ # Power users (specialized)
├── mcp-server.md
├── mcp-tools.md
├── custom-workflows.md
└── multi-source.md
```
---
## Category Guidelines
### Getting Started
**Purpose:** Get new users to their first success quickly
**Characteristics:**
- Minimal prerequisites
- Step-by-step instructions
- Copy-paste ready commands
- Screenshots/output examples
**Files:**
- `01-installation.md` - Install the tool
- `02-quick-start.md` - 3 commands to first skill
- `03-your-first-skill.md` - Complete walkthrough
- `04-next-steps.md` - Where to go after first success
---
### User Guide
**Purpose:** Teach common tasks and concepts
**Characteristics:**
- Task-oriented
- Practical examples
- Best practices
- Common patterns
**Files:**
- `01-core-concepts.md` - How it works
- `02-scraping.md` - All scraping options
- `03-enhancement.md` - AI enhancement
- `04-packaging.md` - Platform export
- `05-workflows.md` - Workflow presets
- `06-troubleshooting.md` - Problem solving
---
### Reference
**Purpose:** Authoritative technical information
**Characteristics:**
- Comprehensive
- Precise
- Organized for lookup
- Always accurate
**Files:**
- `CLI_REFERENCE.md` - All 20 CLI commands
- `MCP_REFERENCE.md` - 26 MCP tools
- `CONFIG_FORMAT.md` - JSON schema
- `ENVIRONMENT_VARIABLES.md` - All env vars
---
### Advanced
**Purpose:** Specialized topics for power users
**Characteristics:**
- Assumes basic knowledge
- Deep dives
- Complex scenarios
- Integration topics
**Files:**
- `mcp-server.md` - MCP server setup
- `mcp-tools.md` - Advanced MCP usage
- `custom-workflows.md` - Creating workflows
- `multi-source.md` - Unified scraping
---
## Naming Conventions
### Files
- **getting-started:** `01-topic.md` (numbered for order)
- **user-guide:** `01-topic.md` (numbered for order)
- **reference:** `TOPIC_REFERENCE.md` (uppercase, descriptive)
- **advanced:** `topic.md` (lowercase, specific)
### Headers
- H1: Title with version
- H2: Major sections
- H3: Subsections
- H4: Details
Example:
```markdown
# Topic Guide
> **Skill Seekers v3.1.0**
## Major Section
### Subsection
#### Detail
```
---
## Cross-References
Link to related docs using relative paths:
```markdown
<!-- Within same directory -->
See [Troubleshooting](06-troubleshooting.md)
<!-- Up one directory, then into reference -->
See [CLI Reference](../reference/CLI_REFERENCE.md)
<!-- Up two directories (to root) -->
See [Contributing](../../CONTRIBUTING.md)
```
---
## Maintenance
### Keeping Docs Current
1. **Update with code changes** - Docs must match implementation
2. **Version in header** - Keep version current
3. **Last updated date** - Track freshness
4. **Deprecate old files** - Don't delete, redirect
### Review Checklist
Before committing docs:
- [ ] Commands actually work (tested)
- [ ] No phantom commands documented
- [ ] Links work
- [ ] Version number correct
- [ ] Date updated
---
## Adding New Documentation
### New User Guide
1. Add to `user-guide/` with next number
2. Update `docs/README.md` navigation
3. Add to table of contents
4. Link from related guides
### New Reference
1. Add to `reference/` with `_REFERENCE` suffix
2. Update `docs/README.md` navigation
3. Link from user guides
4. Add to troubleshooting if relevant
### New Advanced Topic
1. Add to `advanced/` with descriptive name
2. Update `docs/README.md` navigation
3. Link from appropriate user guide
---
## Deprecation Strategy
When content becomes outdated:
1. **Don't delete immediately** - Breaks external links
2. **Add deprecation notice**:
```markdown
> ⚠️ **DEPRECATED**: This document is outdated.
> See [New Guide](path/to/new.md) for current information.
```
3. **Move to archive** after 6 months:
```
docs/archive/legacy/
```
4. **Update navigation** to remove deprecated links
---
## Contributing
### Doc Changes
1. Edit relevant file
2. Test all commands
3. Update version/date
4. Submit PR
### New Doc
1. Choose appropriate category
2. Follow naming conventions
3. Add to README.md
4. Cross-link related docs
---
## See Also
- [Docs README](README.md) - Navigation hub
- [Contributing Guide](../CONTRIBUTING.md) - How to contribute
- [Repository README](../README.md) - Project overview