deblan-mirror/wails
1
0
Fork 0
mirror of https://github.com/wailsapp/wails.git synced 2026-03-14 22:55:48 +01:00
Code Issues Projects Releases Packages Wiki Activity
wails/docs/DOCUMENTATION_REDESIGN_STATUS.md

13 KiB
Raw Blame History

Wails v3 Documentation Redesign - Status Report

Branch: docs-redesign-netflix
Started: 2025-10-01
Approach: Netflix Documentation Principles

Netflix Principles Applied

  1. Start with the Problem ✅

    • Homepage explains the desktop app dilemma
    • "Why Wails?" addresses pain points first
    • Real-world impact metrics (memory, bundle size, startup time)

  2. Progressive Disclosure ✅

    • Quick Start for beginners (4 steps)
    • Tutorials for hands-on learners
    • Features for systematic exploration
    • Reference for deep dives

  3. Real Production Examples 🔄 In Progress

    • Tutorials use real scenarios (Todo, Dashboard, File Manager)
    • No toy examples
    • Production-ready patterns

  4. Story-Code-Context Pattern ✅

    • Why (problem) → How (code) → When (context)
    • Every major section follows this pattern

  5. Scannable Content ✅

    • Clear headings
    • Code blocks with syntax highlighting
    • Callout boxes for important info
    • Visual placeholders for diagrams

  6. Failure Scenarios ✅

    • Troubleshooting sections
    • Common errors documented
    • "When NOT to use" guidance

Completed Sections

✅ Infrastructure

  • Upgraded Starlight to v0.30.0
  • Upgraded Astro to v5.0.0
  • Configured D2 diagram support
  • Created comprehensive navigation structure
  • Set up directory structure for all sections

✅ Homepage (index.mdx)

  • Problem-solution framing
  • Real-world impact metrics
  • Quick example with code
  • Learning path guidance
  • Visual placeholders for diagrams
  • Community links

✅ Quick Start Section

  • Why Wails? - Problem-first approach, comparisons, decision tree
  • Installation - Step-by-step with troubleshooting
  • Your First App - Working code, explanations, customisation
  • Next Steps - Learning paths, feature reference, use cases

In Progress / Planned Sections

🔄 Core Concepts (Priority: High)

  • How Wails Works (architecture with D2 diagrams)
  • Application Lifecycle
  • Go-Frontend Bridge (detailed explanation)
  • Build System

🔄 Features Section (Priority: High)

Reorganised from existing "Learn" section with improvements:

Windows

  • Window Basics (from existing windows.mdx)
  • Window Options (comprehensive options reference)
  • Multiple Windows (new, with examples)
  • Frameless Windows (from existing frameless guide)
  • Window Events (from existing events.mdx)

Menus

  • Application Menus (from existing application-menu.mdx)
  • Context Menus (from existing context-menu.mdx)
  • System Tray Menus (from existing systray.mdx)
  • Menu Reference (from existing menu-reference.mdx)

Bindings & Services

  • Method Binding (from existing bindings.mdx)
  • Services (from existing services.mdx)
  • Advanced Binding (from existing advanced-binding.mdx)
  • Best Practices (from existing binding-best-practices.mdx)

Events

  • Event System (from existing events.mdx)
  • Application Events (extract from events.mdx)
  • Window Events (extract from events.mdx)
  • Custom Events (new section)

Dialogs

  • File Dialogs (from existing dialogs.mdx)
  • Message Dialogs (from existing dialogs.mdx)
  • Custom Dialogs (new section)

Other Features

  • Clipboard (from existing clipboard.mdx)
  • Drag & Drop (new, comprehensive)
  • Keyboard Shortcuts (from existing keybindings.mdx)
  • Notifications (from existing notifications.mdx)
  • Screens API (from existing screens.mdx)
  • Environment (from existing environment.mdx)

Platform-Specific

  • macOS Dock (from existing dock.mdx)
  • macOS Toolbar (new)
  • Windows UAC (from existing windows-uac.mdx)
  • Linux Desktop (new)

🔄 Tutorials Section (Priority: High)

  • Overview (tutorial index with learning paths)
  • Todo App with React (complete, production-ready)
  • Dashboard with Vue (real-time data, charts)
  • Notes App with Vanilla JS (simple, beginner-friendly)
  • File Operations (dialogs, drag-drop)
  • Database Integration (SQLite, best practices)
  • System Tray Integration (background app pattern)
  • Auto-Updates with Sparkle (from existing sparkle-updates.mdx)
  • Multi-Window Applications (advanced)
  • Custom Protocols (deep linking)
  • Native Integrations (platform-specific features)

🔄 Guides Section (Priority: Medium)

Task-oriented, "when to use" focus:

Development

  • Project Structure (best practices)
  • Development Workflow (daily tasks)
  • Debugging (frontend + backend)
  • Testing (unit, integration, e2e)

Building & Packaging

  • Building Applications (from existing build.mdx)
  • Cross-Platform Builds (new)
  • Code Signing (from existing signing.mdx)
  • Windows Packaging (new)
  • macOS Packaging (new)
  • Linux Packaging (new)
  • MSIX Packaging (from existing msix-packaging.mdx)

Distribution

  • Auto-Updates (comprehensive guide)
  • File Associations (from existing file-associations.mdx)
  • Custom Protocols (from existing custom-protocol-association.mdx)
  • Single Instance (from existing single-instance.mdx)

Integration Patterns

  • Using Gin Router (from existing gin-routing.mdx)
  • Gin Services (from existing gin-services.mdx)
  • Database Integration (patterns, best practices)
  • REST APIs (calling external APIs)

Advanced Topics

  • Custom Templates (from existing custom-templates.mdx)
  • WML (Wails Markup) (new, comprehensive)
  • Panic Handling (from existing panic-handling.mdx)
  • Security Best Practices (new)

🔄 API Reference Section (Priority: Medium)

Complete API documentation:

  • Overview (API structure, conventions)
  • Application API (all methods, options)
  • Window API (all methods, options, events)
  • Menu API (menu types, methods)
  • Events API (event types, handlers)
  • Dialogs API (all dialog types)
  • Runtime API (browser, clipboard, environment)
  • CLI Reference (all commands, flags)

🔄 Contributing Section (Priority: High)

For Wails developers (not users):

  • Getting Started (contributor onboarding)
  • Development Setup (building from source)

Architecture

  • Overview (high-level architecture with D2)
  • CLI Layer (command structure, task system)
  • Runtime Layer (application, services, bindings)
  • Platform Layer (OS integrations)
  • Build System (Taskfile, generators, packagers)

Codebase Guide

  • Repository Structure (v3 layout)
  • Application Package (pkg/application deep dive)
  • Internal Packages (internal/* explanation)
  • Platform Bindings (pkg/mac, pkg/w32, etc.)
  • Testing (test structure, running tests)

Development Workflows

  • Building from Source

  • Running Tests (unit, integration, examples)

  • Debugging (debugging Wails itself)

  • Adding Features (contribution workflow)

  • Fixing Bugs (bug fix workflow)

  • Coding Standards (Go style, naming conventions)

  • Pull Request Process (PR template, review process)

  • Documentation (how to document new features)

🔄 Migration Section (Priority: Medium)

  • From v2 to v3 (comprehensive migration guide)
  • From Electron (comparison, migration patterns)
  • From Tauri (comparison, migration patterns)

🔄 Troubleshooting Section (Priority: Low)

  • Common Issues (FAQ-style)
  • Platform-Specific Issues
  • Build Errors
  • Runtime Errors

Visual Placeholders Added

All major sections include detailed placeholders for:

  1. Architecture Diagrams (D2 format)

    • System architecture
    • Data flow diagrams
    • Component relationships

  2. Comparison Charts

    • Memory usage comparisons
    • Bundle size comparisons
    • Startup time comparisons

  3. Screenshots

    • Example applications
    • UI components
    • Development workflow

  4. Flowcharts

    • Decision trees
    • Workflow diagrams
    • Process flows

Each placeholder includes:

  • Detailed description of what should be shown
  • Style guidelines
  • Specific data points or elements
  • Color scheme suggestions

Documentation Quality Standards

Writing Style

  • ✅ International English (ise, our, re, ogue)
  • ✅ Conversational but professional tone
  • ✅ Active voice, present tense
  • ✅ Short paragraphs, scannable
  • ✅ Code examples before explanation

Structure

  • ✅ Problem → Solution → Context pattern
  • ✅ Progressive disclosure (TL;DR → Details)
  • ✅ Clear headings (H2, H3 hierarchy)
  • ✅ Callout boxes for important info
  • ✅ Cross-references to related content

Code Examples

  • ✅ Complete, runnable code
  • ✅ Syntax highlighting
  • ✅ Comments explaining key points
  • ✅ Error handling included
  • ✅ Real-world scenarios (not toy examples)

Technical Accuracy

  • 🔄 Verified against v3 codebase (in progress)
  • 🔄 Tested code examples (in progress)
  • 🔄 Up-to-date API references (in progress)
  • 🔄 Platform-specific notes (in progress)

Next Steps (Priority Order)

  1. Core Concepts - Essential for understanding

    • Architecture with D2 diagrams
    • Lifecycle explanation
    • Bridge mechanism

  2. Complete Tutorials - Learning by doing

    • Todo app (React + SQLite)
    • Dashboard (Vue + real-time)
    • File operations

  3. Features Documentation - Reorganise existing content

    • Migrate from old structure
    • Add missing sections
    • Verify accuracy

  4. API Reference - Complete technical docs

    • Auto-generate where possible
    • Manual documentation for complex APIs
    • Code examples for each method

  5. Contributing Guide - Onboard new contributors

    • Architecture deep dive
    • Codebase walkthrough
    • Development workflows

  6. Migration Guides - Help users upgrade

    • v2 to v3 (critical)
    • From other frameworks

  7. Polish & Review - Final quality pass

    • Verify all links
    • Test all code examples
    • Add remaining diagrams
    • Proofread everything

Metrics & Goals

Target Metrics

  • Time to First Success: <30 minutes (new user to working app)
  • Documentation Coverage: 100% of public APIs
  • Code Example Coverage: 100% of tutorials, 80% of features
  • Visual Aids: Diagrams for all architectural concepts
  • Cross-References: Every page links to related content

Success Criteria

  • New users can build an app in 30 minutes
  • All public APIs documented with examples
  • Zero broken links
  • All code examples tested and working
  • Community feedback positive (Discord, GitHub)

Files Created/Modified

New Files

  • docs/astro.config.mjs (comprehensive navigation)
  • docs/package.json (upgraded dependencies)
  • docs/src/content/docs/index.mdx (new homepage)
  • docs/src/content/docs/quick-start/why-wails.mdx
  • docs/src/content/docs/quick-start/installation.mdx
  • docs/src/content/docs/quick-start/first-app.mdx
  • docs/src/content/docs/quick-start/next-steps.mdx
  • docs/create-dirs.ps1 (directory creation script)
  • docs/DOCUMENTATION_REDESIGN_STATUS.md (this file)

Directories Created

  • docs/src/content/docs/quick-start/
  • docs/src/content/docs/concepts/
  • docs/src/content/docs/features/ (with subdirectories)
  • docs/src/content/docs/guides/ (with subdirectories)
  • docs/src/content/docs/reference/ (with subdirectories)
  • docs/src/content/docs/contributing/ (with subdirectories)
  • docs/src/content/docs/migration/

Modified Files

  • docs/astro.config.mjs (complete restructure)
  • docs/package.json (version upgrades)
  • docs/src/content/docs/index.mdx (complete rewrite)

Estimated Completion

Completed: ~15%

  • Infrastructure: 100%
  • Quick Start: 100%
  • Homepage: 100%

Remaining: ~85%

  • Core Concepts: 0%
  • Features: 0% (content exists, needs reorganisation)
  • Tutorials: 10% (structure done, content needed)
  • Guides: 0% (content exists, needs reorganisation)
  • API Reference: 0%
  • Contributing: 0%
  • Migration: 0%

Time Estimate

  • Remaining work: 40-60 hours
  • With automation: 30-40 hours (auto-generate API docs)
  • With team: 20-30 hours (parallel work on sections)

Notes for Continuation

  1. Preserve Existing Content: Don't delete existing docs, migrate and improve them
  2. Test All Code: Every code example must be tested and working
  3. Add Diagrams: Use D2 for all architectural diagrams
  4. Cross-Reference: Link related content extensively
  5. Get Feedback: Share with community early and often
  6. Iterate: Documentation is never "done", plan for updates

Questions for Review

  1. Navigation Structure: Is the sidebar organisation intuitive?
  2. Learning Paths: Do the three paths (tutorials, features, guides) make sense?
  3. Tone: Is the conversational style appropriate?
  4. Depth: Is the Quick Start too detailed or just right?
  5. Visuals: Are the placeholder descriptions clear enough for designers?

This is a living document. Update as work progresses.