Add comprehensive wiki home page with guidelines and structure
162
Home.md
Normal file
162
Home.md
Normal file
@@ -0,0 +1,162 @@
|
|||||||
|
# 🏠 DanceLessonsCoach Wiki Home
|
||||||
|
|
||||||
|
Welcome to the DanceLessonsCoach Wiki! This is your guide to understanding our project documentation structure, contribution guidelines, and how to navigate our knowledge base.
|
||||||
|
|
||||||
|
## 🗺️ Wiki Structure & Audience Guide
|
||||||
|
|
||||||
|
### 📋 Documentation Types & Their Audience
|
||||||
|
|
||||||
|
| Document Type | Location | Primary Audience | Purpose |
|
||||||
|
|--------------|----------|------------------|---------|
|
||||||
|
| **Product Vision & Features** | Wiki Pages | Users, Product Managers, Stakeholders | Describe what our product does and its benefits |
|
||||||
|
| **User Stories & Workflows** | Wiki Pages | Developers, Product Owners, Designers | Explain user journeys and feature requirements |
|
||||||
|
| **Security Documentation** | Wiki Pages | Security Teams, Developers, Admins | Detail security policies and implementations |
|
||||||
|
| **Technical Implementation** | Gitea Issues | Developers, Architects | Code-level details, API specs, database schemas |
|
||||||
|
| **Architecture Decisions** | ADR Folder | Architects, Tech Leads | Rationale behind technical choices |
|
||||||
|
| **BDD Test Scenarios** | Feature Files | QA, Developers | Behavioral test specifications |
|
||||||
|
|
||||||
|
## 🎨 Documentation Standards
|
||||||
|
|
||||||
|
### 📝 Wiki Page Guidelines
|
||||||
|
|
||||||
|
1. **Audience-First Approach:**
|
||||||
|
- Write for the intended reader (non-technical for product pages, technical for implementation)
|
||||||
|
- Avoid jargon in user-facing documentation
|
||||||
|
- Use clear, simple language
|
||||||
|
|
||||||
|
2. **Visual Consistency:**
|
||||||
|
- **Mermaid Diagrams:** Use forest theme for all flowcharts
|
||||||
|
- **Code Blocks:** Use appropriate language tags (go, http, sql, etc.)
|
||||||
|
- **Emoji Usage:** Use emojis sparingly for section headers
|
||||||
|
|
||||||
|
3. **Mermaid Forest Theme:**
|
||||||
|
```mermaid
|
||||||
|
%%{init: {'theme': 'forest'}}%%
|
||||||
|
graph TD
|
||||||
|
A[Start] --> B[Process]
|
||||||
|
B --> C[End]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 🔒 Security Documentation Rules
|
||||||
|
|
||||||
|
- **Critical Security Info:** Always in dedicated security pages
|
||||||
|
- **Never in Code Comments:** Security policies belong in wiki, not code
|
||||||
|
- **Reference Standards:** Link to OWASP, CIS, GDPR where applicable
|
||||||
|
|
||||||
|
## 📚 Current Wiki Pages
|
||||||
|
|
||||||
|
### 🌟 Product & Vision
|
||||||
|
- **[User Management & Authentication Vision](User-Management-Product-Vision.-)** - Our product roadmap and user personas
|
||||||
|
- **[User Story Implementation](User-Story-Implementation-Workflow.-)** - How users interact with our features
|
||||||
|
|
||||||
|
### 🔐 Security
|
||||||
|
- **[Admin-Only Password Reset](Admin-Only-Password-Reset-Security.-)** - Critical security policies and workflows
|
||||||
|
|
||||||
|
### 🛠️ Technical (in Gitea Issues)
|
||||||
|
- User Registration (#4)
|
||||||
|
- User Login (#5)
|
||||||
|
- Admin Password Reset (#7)
|
||||||
|
- JWT Secret Rotation (#8)
|
||||||
|
- User Profile Management (#6)
|
||||||
|
|
||||||
|
## 🤝 Contribution Guidelines
|
||||||
|
|
||||||
|
### 📝 Creating New Wiki Pages
|
||||||
|
|
||||||
|
1. **Determine the Audience:** Who will read this? Users or developers?
|
||||||
|
2. **Choose the Right Location:** Product info → Wiki, Technical details → Issues
|
||||||
|
3. **Follow the Template:** Use existing pages as examples
|
||||||
|
4. **Apply Forest Theme:** For any mermaid diagrams
|
||||||
|
5. **Link Related Documents:** Connect to issues, ADRs, or other wiki pages
|
||||||
|
|
||||||
|
### 🔧 Technical Documentation
|
||||||
|
|
||||||
|
- **Belongs in Gitea Issues:** API endpoints, database schemas, code snippets
|
||||||
|
- **Wiki is for Concepts:** Explain the "what" and "why", not the "how"
|
||||||
|
- **Reference Implementation:** Link from wiki to relevant issues
|
||||||
|
|
||||||
|
### 🎨 Mermaid Diagram Guide
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
%%{init: {'theme': 'forest'}}%%
|
||||||
|
graph LR
|
||||||
|
A[Wiki Content] --> B{Technical?}
|
||||||
|
B -->|Yes| C[Gitea Issue]
|
||||||
|
B -->|No| D[Wiki Page]
|
||||||
|
C --> E[Code Implementation]
|
||||||
|
D --> F[User Documentation]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Best Practices:**
|
||||||
|
- Keep diagrams simple and focused
|
||||||
|
- Use forest theme for consistency
|
||||||
|
- Limit to 7-10 nodes per diagram
|
||||||
|
- Add descriptive labels
|
||||||
|
|
||||||
|
## 🚀 Getting Started
|
||||||
|
|
||||||
|
### For New Contributors:
|
||||||
|
1. Read the [Product Vision](User-Management-Product-Vision.-) to understand our goals
|
||||||
|
2. Check existing [Gitea Issues](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/issues) for technical details
|
||||||
|
3. Review the [Security Documentation](Admin-Only-Password-Reset-Security.-) for critical policies
|
||||||
|
4. Follow the forest theme for any new diagrams
|
||||||
|
|
||||||
|
### For Users:
|
||||||
|
- Start with our [Product Vision](User-Management-Product-Vision.-)
|
||||||
|
- Explore [User Stories](User-Story-Implementation-Workflow.-) to see how features work
|
||||||
|
- Check the security page if you're an admin
|
||||||
|
|
||||||
|
### For Developers:
|
||||||
|
- Technical details are in [Gitea Issues](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/issues)
|
||||||
|
- Wiki provides context and requirements
|
||||||
|
- Always link between wiki and implementation issues
|
||||||
|
|
||||||
|
## 📈 Documentation Roadmap
|
||||||
|
|
||||||
|
### Coming Soon:
|
||||||
|
- **API Documentation Guide** - How we document endpoints
|
||||||
|
- **ADR Template** - Standard format for architecture decisions
|
||||||
|
- **BDD Test Writing Guide** - Best practices for feature files
|
||||||
|
- **Security Checklist** - For new feature development
|
||||||
|
|
||||||
|
### Future Enhancements:
|
||||||
|
- Interactive diagrams with mermaid
|
||||||
|
- Video tutorials for complex workflows
|
||||||
|
- User persona deep dives
|
||||||
|
- Admin guide with screenshots
|
||||||
|
|
||||||
|
## 🤖 AI Assistance
|
||||||
|
|
||||||
|
Our wiki is maintained with help from **Mistral Vibe** - our AI documentation assistant. If you need help:
|
||||||
|
- Ask for clarification on any documentation
|
||||||
|
- Request new diagrams or examples
|
||||||
|
- Suggest improvements to existing content
|
||||||
|
|
||||||
|
## 🎯 Our Documentation Philosophy
|
||||||
|
|
||||||
|
> "Documentation should be a bridge, not a barrier."
|
||||||
|
|
||||||
|
**Principles:**
|
||||||
|
1. **Clear:** Easy to understand for the intended audience
|
||||||
|
2. **Concise:** Get to the point without unnecessary details
|
||||||
|
3. **Current:** Always up-to-date with the latest changes
|
||||||
|
4. **Connected:** Well-linked between related documents
|
||||||
|
5. **Consistent:** Same style and format throughout
|
||||||
|
|
||||||
|
**Avoid:**
|
||||||
|
- ❌ Duplicate information
|
||||||
|
- ❌ Outdated content
|
||||||
|
- ❌ Overly technical language in user docs
|
||||||
|
- ❌ Unlinked/orphaned pages
|
||||||
|
|
||||||
|
## 📞 Need Help?
|
||||||
|
|
||||||
|
- **Documentation Issues:** Open a new issue with "docs" label
|
||||||
|
- **Technical Questions:** Ask in the relevant Gitea issue
|
||||||
|
- **Security Concerns:** Contact admins immediately
|
||||||
|
- **General Questions:** Check our [Discussions](https://gitea.arcodange.lab/arcodange/dance-lessons-coach/discussions)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Last updated: 2026-04-08*
|
||||||
|
*Maintained by: DanceLessonsCoach Team 💃🕺*
|
||||||
Reference in New Issue
Block a user