Revamp Docs for the component and the example app

[darko-mijic]

Summary

This PR improves the documentation for the @convex-dev/persistent-text-streaming component and its example app. The aim is to make the docs clearer, more thorough, and easier to follow for developers who want to use the component.

I know the main README.md gets pulled into the Convex docs site, so I tried to keep it concise where it counts. That said, I went a bit verbose in some spots to cover all the bases—hopefully, there’s plenty here that can be cherry-picked to improve the official docs!

What’s Changed

Main README.md:

• Clarified the core problem the component solves (speed vs. durability in text streaming).
• Provided a more detailed explanation of the "Intelligent Dual-Path Streaming" solution.
• Restructured for better readability and flow, aligning with common documentation best practices.
• Added a "Usage Overview" section for a quick understanding of integration steps.
• Included a "How It Works" section detailing the isDriven flag mechanism.
• Prominently links to the updated example/README.md for detailed implementation guidance.

example/README.md:

• Expanded from a basic setup guide to a comprehensive walkthrough of how the component is used within the example chat application.
• Includes detailed code snippets and explanations for:
  • Backend component registration and schema setup.
  • Initialization of the PersistentTextStreaming client.
  • Stream ID creation and management within the application logic.
  • Implementation of the HTTP streaming action.
  • Frontend usage of the useStream hook, including the isDriven flag.
  • How to view component-specific data in the Convex Dashboard.
• Aims to serve as a robust, practical reference for users.

Why This Matters

The original READMEs were solid but left room to grow. I wanted to:

• Explain why this component is built the way it is.
• Give clearer guidance on both the big picture and the nitty-gritty details of using it.
• Make life easier for devs who are new to the component or want a deeper understanding.
• Ensure the docs feel polished and ready for the official Convex component docs.

These updates should help developers pick up the persistent-text-streaming component faster and use it with confidence. Looking forward to feedback!

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[ianmacartney]

Hey Darko sorry I didn't get a chance to review this this week, but thanks for all the effort put in! It's a pretty big rewrite - how much of it was AI btw? Are there sections you feel are especially necessary to change? I only ask b/c it'll be less consistent with other component docs

…

On Fri, May 16, 2025 at 8:31 PM Darko Mijić ***@***.***> wrote: Summary This PR improves the documentation for the @convex-dev/persistent-text-streaming component and its example app. The aim is to make the docs clearer, more thorough, and easier to follow for developers who want to use the component. I know the main README.md gets pulled into the Convex docs site, so I tried to keep it concise where it counts. That said, I went a bit verbose in some spots to cover all the bases—hopefully, there’s plenty here that can be cherry-picked to improve the official docs! What’s Changed *Main README.md:* - Clarified the core problem the component solves (speed vs. durability in text streaming). - Provided a more detailed explanation of the "Intelligent Dual-Path Streaming" solution. - Restructured for better readability and flow, aligning with common documentation best practices. - Added a "Usage Overview" section for a quick understanding of integration steps. - Included a "How It Works" section detailing the isDriven flag mechanism. - Prominently links to the updated example/README.md for detailed implementation guidance. *example/README.md:* - Expanded from a basic setup guide to a comprehensive walkthrough of how the component is used within the example chat application. - Includes detailed code snippets and explanations for: - Backend component registration and schema setup. - Initialization of the PersistentTextStreaming client. - Stream ID creation and management within the application logic. - Implementation of the HTTP streaming action. - Frontend usage of the useStream hook, including the isDriven flag. - How to view component-specific data in the Convex Dashboard. - Aims to serve as a robust, practical reference for users. Why This Matters The original READMEs were solid but left room to grow. I wanted to: - Explain *why* this component is built the way it is. - Give clearer guidance on both the big picture and the nitty-gritty details of using it. - Make life easier for devs who are new to the component or want a deeper understanding. - Ensure the docs feel polished and ready for the official Convex component docs. These updates should help developers pick up the persistent-text-streaming component faster and use it with confidence. Looking forward to feedback! ------------------------------ By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice. ------------------------------ You can view, comment on, or merge this pull request online at: #3 Commit Summary - eebaa18 <eebaa18> Docs: Enhance root and example app README files for clarity and detail File Changes (2 files <https://github.com/get-convex/persistent-text-streaming/pull/3/files>) - *M* README.md <https://github.com/get-convex/persistent-text-streaming/pull/3/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5> (300) - *M* example/README.md <https://github.com/get-convex/persistent-text-streaming/pull/3/files#diff-bc501e6e1e9420017b2d954e834fd8c3afb7daf9e2eb780c46c491099a7c2f0e> (407) Patch Links: - https://github.com/get-convex/persistent-text-streaming/pull/3.patch - https://github.com/get-convex/persistent-text-streaming/pull/3.diff — Reply to this email directly, view it on GitHub <#3>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQW52AKKVQFDS5DKHTGD262UQHAVCNFSM6AAAAAB5KCXKIGVHI2DSMVQWIX3LMV43ASLTON2WKOZTGA3TAMRVG4ZDSNQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[darko-mijic]

No worries. It would be amazing if you just take the root readme. And please, submit the docs for this component to https://context7.com/