BuilderIO · adamdbradley · Mar 21, 2023 · Mar 21, 2023 · Mar 21, 2023
diff --git a/DEVELOPER.md b/DEVELOPER.md
@@ -13,12 +13,21 @@ See the [distribution](https://partytown.builder.io/distribution) section about
 
 ## Submitting Issues And Writing Tests
 
-We need your help! If you found a bug, it's best to create a [Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) that replicates the issue using a test page. In the [tests directory](https://github.com/BuilderIO/partytown/tree/main/tests), copy one of the directories, such as `tests/platform/document`, and recreate the issue you've found.
+We need your help! If you found a bug, it's best to create a [Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) that replicates the issue using a test page.
+
+- Minimal Reproduction Case: If maintainers and contributors are unable to reproduce the same error, then it makes it very difficult to debug and fix. Any issued opened without a minimal reproduction example will be closed.
+- E2E Test: A good example of an End-to-end test is one where the test fails before the fix, and passes after the fix. But also, all the other tests pass too.
+
+In the [tests directory](https://github.com/BuilderIO/partytown/tree/main/tests), copy one of the directories, such as `tests/platform/document`, and recreate the issue you've found.
 
 Follow the [manual testing](#manual-testing) directions on how to start the local dev server. Next, the more you can describe the debug and pin-point the issue the better, and any fixes to the runtime to solve the problem would be awesome. 🎉
 
 If the PR fixes the issue, then creating an [end-to-end test](#e2e-testing) would help ensure no regressions happen over time.
 
+Additionally, Github issues is a place to explain a problem in detail, along with a reproduction case for maintainers. However, Github issues is not the best place to ask how-to questions since project contributors and maintainers don’t have the capacity to debug external websites and the many third-party scripts. Any issues opened asking that are not following these guidelines will be closed.
+
+Please also see the [FAQ section](https://partytown.builder.io/faq) for more info
+
 ## Plugin Authors / Developers
 
 If you are the author / developer of any 3rd party plugin / library, and want to ensure that your library works with Partytown, we would love to work with you to ensure it does!

diff --git a/README.md b/README.md
@@ -11,12 +11,15 @@
 
 Partytown is a lazy-loaded library to help relocate resource intensive scripts into a [web worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API), and off of the [main thread](https://developer.mozilla.org/en-US/docs/Glossary/Main_thread). Its goal is to help speed up sites by dedicating the main thread to your code, and offloading third-party scripts to a web worker.
 
+> Note: Partytown is still in beta and not guaranteed to work in every scenario. Please see our [FAQ](https://partytown.builder.io/faq) and [Trade-Off](https://partytown.builder.io/trade-offs) sections for more info.
+
 The philosophy is that the main thread should be dedicated to your code, and any scripts that are not required to be in the [critical path](https://developers.google.com/web/fundamentals/performance/critical-rendering-path) should be moved to a web worker. Main thread performance is, without question, more important than web worker thread performance.
 
 - [Getting Started](https://partytown.builder.io/getting-started)
 - [Integrations](https://partytown.builder.io/integrations)
 - [Configuration](https://partytown.builder.io/configuration)
 - [Releases](https://github.com/BuilderIO/partytown/releases)
+- [FAQs](https://partytown.builder.io/faq)
 
 ![Without Partytown and With Partytown: Your code and third-party code compete for main thread resources](https://user-images.githubusercontent.com/452425/152393346-6f721a4f-3f66-410a-8878-a2b49e24307f.png)
 

diff --git a/docs/_table-of-contents.md b/docs/_table-of-contents.md
@@ -2,6 +2,7 @@
 
 - [Introduction](/)
   - [How Does It Work?](/how-does-partytown-work)
+  - [FAQs](/faq)
   - [Trade-Offs](/trade-offs)
   - [Browser Support](/browser-support)
 - [Getting Started](/getting-started)

diff --git a/docs/faq.md b/docs/faq.md
@@ -0,0 +1,40 @@
+---
+title: FAQs
+---
+
+## Can all scripts use Partytown?
+
+Not necessarily. While Partytown covers many cases that allow it to work great in many cases, there are also scenarios where your script may hit an internal error and silently fail. We encourage you to thoroughly test when running any scripts first in a development environment, and then in production. Please also see the [Trade-Offs](/trade-offs) docs.
+
+## How do I know when a script is not working with Partytown?
+
+Test test test! There are endless scenarios in which a script could have been written, and the tricks they could be doing. While Partytown has worked to [test](/tests/) many of these scenarios, there's a good chance a certain example isn't being accounted for. We encourage you to thoroughly test when running any scripts first in a development environment, and then in production.
+
+## What do I do if my script is not working with Partytown?
+
+Please first search through the [Github issues](https://github.com/BuilderIO/partytown/issues) for a similar issue. If a similar issue exists, please add a comment with as much additional information as possible.
+
+If a similar [issue](https://github.com/BuilderIO/partytown/issues) does not already exist, please [open an issue](https://github.com/BuilderIO/partytown/issues/new/choose) that includes:
+
+- Minimal Reproduction Case: If maintainers and contributors are unable to reproduce the same error, then it makes it very difficult to debug and fix. Any issued opened without a minimal reproduction example will be closed.
+- E2E Test: A good example of an End-to-end test is one where the test fails before the fix, and passes after the fix. But also, all the other tests pass too. Please see [Submitting Issues And Writing Tests](https://github.com/BuilderIO/partytown/blob/main/DEVELOPER.md#submitting-issues-and-writing-tests) for more details.
+
+## Why do some scripts work, and others don't with Partytown?
+
+Most of yesterday's and today's third-party scripts were built from the ground-up to work only on the main UI thread, rather than from a web worker which does not have access to the DOM or window. Partytown does its best to access the main thread from a web-worker, synchronously so the script continues to work as expected. However, because this architecture is different from what's the original designers expected, the script may have an internal error. For all these reasons we encourage you to first thoroughly test your scripts when using them with Partytown. Please also see the [Trade-Offs](/trade-offs) docs.
+
+## Will you debug why my script is not working for me?
+
+Unfortunately, the project contributors and maintainers don’t have the capacity to debug every single third-party script on external websites. As an Open-Source project, Partytown's goal is to help encourage the community to assist one another. Helping to improvement the project can come in many forms:
+
+- [Opening issues](https://github.com/BuilderIO/partytown/blob/main/DEVELOPER.md#submitting-issues-and-writing-tests) with minimal reproduction cases
+- Creating fixes with [Pull Requests](https://github.com/BuilderIO/partytown/blob/main/DEVELOPER.md#submitting-issues-and-writing-tests)
+- Adding [End-to-end tests](/tests/)
+
+Additionally, Github issues is a place to explain a problem in detail, along with a reproduction case for maintainers. However, Github issues is not the best place to ask how-to questions since project contributors and maintainers don’t have the capacity to debug external websites and the many third-party scripts. Any issues opened asking that are not following these guidelines will be closed.
+
+## Is Partytown production ready?
+
+Many sites are already successfully using Partytown in production. However, what's most important is testing your scripts first, as what works for one website using a certain third-party script, may not work for your site using a different script. If your scripts work in production that’s great, they shouldn't suddenly stop working (no different that a traditional third-party script).
+
+However, if you're struggling with a certain scenario, please see the [Submitting Issues And Writing Tests](https://github.com/BuilderIO/partytown/blob/main/DEVELOPER.md#submitting-issues-and-writing-tests).
diff --git a/docs/index.md b/docs/index.md
@@ -5,13 +5,14 @@ description: Partytown - Run third-party scripts from a web worker
 
 Partytown is a lazy-loaded library to help relocate resource intensive scripts into a [web worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API), and off of the [main thread](https://developer.mozilla.org/en-US/docs/Glossary/Main_thread). Its goal is to help speed up sites by dedicating the main thread to your code, and offloading third-party scripts to a web worker.
 
-- [Partytown, Google Slides Presentation](https://docs.google.com/presentation/d/10aKHUokby6hQydL_xuOtct4CPwAkgay5l0-FqgO8-3g/edit?usp=sharing)
+> Note: Partytown is still in beta and not guaranteed to work in every scenario. Please see our [FAQ](/faq) and [Trade-Off](/trade-offs) sections for more info.
 
 Even with a fast and highly tuned website following all of today's best practices, it's all too common for your performance wins to be erased the moment third-party scripts are added. By third-party scripts we mean code that is embedded within your site, but not directly under your control. A few examples include: analytics, metrics, ads, A/B testing, trackers, etc.
 
 Partytown is maintained by [Builder.io](https://www.builder.io/) and is currently in [Beta](https://www.builder.io/blog/partytown-is-now-in-beta).
 
-[Smashing Magazine: How Partytown Eliminates Website Bloat From Third-Party Scripts](https://www.smashingmagazine.com/2022/04/partytown-eliminates-website-bloat-third-party-apps/)
+- [Partytown, Google Slides Presentation](https://docs.google.com/presentation/d/10aKHUokby6hQydL_xuOtct4CPwAkgay5l0-FqgO8-3g/edit?usp=sharing)
+- [Smashing Magazine: How Partytown Eliminates Website Bloat From Third-Party Scripts](https://www.smashingmagazine.com/2022/04/partytown-eliminates-website-bloat-third-party-apps/)
 
 ## Goals