From 094bc8c319bd9ca9b3e039e1f8680fd249e5abf8 Mon Sep 17 00:00:00 2001 From: arcodange Date: Wed, 8 Apr 2026 15:31:32 +0200 Subject: [PATCH] Add comprehensive wiki home page with guidelines and structure --- Home.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 Home.md diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..c8d719a --- /dev/null +++ b/Home.md @@ -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 πŸ’ƒπŸ•Ί*