Write user guidance for Dialectic features

[nikomatsakis]

User Guidance Documentation

Status: Planning

Current Understanding

Dialectic has powerful features but lacks clear user guidance on how to use them effectively. Users need documentation that explains:

• How to use Ask Socratic Shell for code exploration
• How to interact with walkthrough comments and reviews
• How to interpret and work with compact references ()
• Best practices for AI collaboration workflows
• Troubleshooting common issues

Next Steps

• Audit existing features and identify documentation gaps
• Create user guide structure in mdbook
• Write getting started tutorial with concrete examples
• Document Ask Socratic Shell workflow and use cases
• Document walkthrough and review features
• Add troubleshooting section for common issues
• Include screenshots and examples of typical workflows

Open Questions

• Should this be integrated into existing mdbook or separate user guide?
• What level of technical detail is appropriate for end users?
• Should we include video walkthroughs or just text/screenshots?

Context

With the compact reference system now complete (#29), users need clear guidance on how to leverage these features effectively. The current documentation focuses on architecture and setup but lacks user-facing workflow guidance.