More docs about differences between Draftail and Draft.js

[thibaudcolas]

The relationship between the two isn't always the clearest.

[github-actions]

Agentic Agentic Triage triggered by this issue.

[github-actions]

🎯 Agentic Issue Triage

This issue requests expanded documentation about the relationship between Draftail and Draft.js. While existing documentation covers this topic (created via issue #19), the request suggests there's room for improvement or expansion.

---

📋 Context & Analysis

Related Documentation:

• Existing doc: docs/DraftjsVsDraftail.md
• Previous issue: Add documentation about differences between Draftail and Draft.js #19 (closed in 2020 after creating the initial documentation)

Potential Areas for Enhancement:

• Clearer positioning of when to use Draftail vs plain Draft.js
• Migration guide from Draft.js to Draftail
• Comparison table of features/capabilities
• Common misconceptions or FAQs
• Architecture diagrams showing the relationship
• Real-world use cases and examples

💡 Suggested Improvements

Documentation Enhancements:

1. Add a comparison table at the top of the doc:

   | Feature | Draft.js | Draftail |
   |---------|----------|----------|
   | Toolbar UI | ❌ Build yourself | ✅ Built-in |
   | Keyboard shortcuts | ⚠️ Manual setup | ✅ Out of the box |
   | Paste filtering | ❌ No | ✅ Automatic |
   | Custom entities | ✅ Yes | ✅ Yes + helpers |

2. Add a decision tree/flowchart to help users choose:

   • "Need full control over everything?" → Draft.js
   • "Want a working editor quickly?" → Draftail
   • "Building a custom editor with unique UX?" → Draft.js
   • "Standard WYSIWYG with customization?" → Draftail

3. Expand the "When to use" section with concrete scenarios:

   • Building a blog editor → Draftail
   • Replicating Google Docs → Draft.js
   • CMS content editing → Draftail
   • Highly custom collaborative editor → Draft.js

4. Add migration section for Draft.js users:

   • How to wrap existing Draft.js setup with Draftail
   • What changes to expect
   • Code examples before/after

5. Include visual examples:

   • Screenshot showing Draftail's built-in toolbar
   • Diagram of the component hierarchy

🔍 Research Resources

For Contributors:

• Draft.js Documentation
• Draft.js Plugins Architecture
• Existing Draftail vs Draft.js doc
• Similar comparison examples:
  • Next.js vs React
  • Gatsby vs Next.js comparisons

User Feedback Sources:

• Issue More clearly explain Draftail's relationship with Draft.js and Wagtail #14 - Original user confusion about the relationship
• Issue Add documentation about differences between Draftail and Draft.js #19 - Initial documentation request
• Stack Overflow questions about Draftail vs Draft.js

✅ Implementation Checklist

• Review current DraftjsVsDraftail.md content
• Identify gaps based on common user questions
• Create comparison table
• Add "When to choose which" section with concrete examples
• Consider adding visual aids (diagrams/screenshots)
• Add migration guide section (if applicable)
• Add FAQ section addressing common misconceptions
• Update navigation/discoverability of the doc
• Review and update related docs that reference this relationship
• Test with someone unfamiliar with both projects for clarity

---

Labels Applied: enhancement, documentation, draftail, medium effort, help wanted

This is a great opportunity for contributors to improve documentation clarity and help new users understand the Draftail ecosystem better!

AI generated by Agentic Triage for #142

To add this workflow in your repository, run gh aw add githubnext/agentics/workflows/issue-triage.md@09e77ed2e49f0612e258db12839e86e8e2a6c692. See usage guide.