chore: Docs improvements (#979)

Co-authored-by: Loren ☺️ <251288+lorensr@users.noreply.github.com>
Co-authored-by: James Watkins-Harvey <mjameswh@users.noreply.github.com>

Author: 3 people

README.md

@@ -9,20 +9,17 @@
   </a>
 </div>
 
-[Temporal](https://temporal.io) is a microservice orchestration platform that enables developers to build scalable applications without sacrificing productivity or reliability. Temporal Server executes units of application logic—Workflows—in a resilient manner that automatically handles intermittent failures and retries failed operations.
+[Temporal](https://temporal.io) is a durable execution system that transparently makes your code durable, fault-tolerant, and simple.
 
-Temporal is a mature technology—it's a fork of Uber's Cadence. Temporal is being developed by Temporal Technologies, a startup by the creators of Cadence.
+"Temporal TypeScript SDK" is the framework for authoring workflows and activities using either the TypeScript or JavaScript programming languages.
 
-## Documentation
-
-The documentation is divided into several sections:
+For documentation and samples, see:
 
+- [Code Samples](https://github.com/temporalio/samples-typescript)
 - [TypeScript SDK docs](https://docs.temporal.io/typescript/introduction)
 - [TypeScript SDK API reference](https://typescript.temporal.io/)
 - [General Temporal docs](https://docs.temporal.io)
 
-We welcome help improving the docs. You can submit issues for things that aren't clear or send pull requests to this repository (for the API reference) or to the [`docs.temporal.io` repository](https://github.com/temporalio/documentation) (for everything else).
-
 ## Packages
 
 This monorepo contains the following packages:
@@ -39,7 +36,7 @@ This monorepo contains the following packages:
 | [`packages/interceptors-opentelemetry/`](packages/interceptors-opentelemetry/)     | [`@temporalio/interceptors-opentelemetry`](https://www.npmjs.com/package/@temporalio/interceptors-opentelemetry)     |
 | [`packages/meta/`](packages/meta/)                                                 | [`temporalio`](https://www.npmjs.com/package/@temporalio/meta) (deprecated)                                          |
 | [`packages/test/`](packages/test/)                                                 | SDK internal tests                                                                                                   |
-| [`packages/create-project/`](packages/create-project/)                             | [`@temporalio/create`](https://www.npmjs.com/package/@temporalio/create-project)                             |
+| [`packages/create-project/`](packages/create-project/)                             | [`@temporalio/create`](https://www.npmjs.com/package/@temporalio/create-project)                                     |
 | [`packages/docs/`](packages/docs/)                                                 | [API docs](https://typescript.temporal.io/)                                                                          |
 
 ## Contributors

packages/activity/src/index.ts

@@ -44,9 +44,9 @@
  * The reason for the Cancellation is available at {@link CancelledFailure.message} or
  * {@link Context#cancellationSignal | Context.cancellationSignal.reason}.
  *
- * There are two ways to handle Activity Cancellation:
+ * Activity implementations should opt-in and subscribe to cancellation using one of the following methods:
  *
- * 1. await on {@link Context.cancelled | `Context.current().cancelled`} or
+ * 1. `await` on {@link Context.cancelled | `Context.current().cancelled`} or
  *    {@link Context.sleep | `Context.current().sleep()`}, which each throw a {@link CancelledFailure}.
  * 1. Pass the context's {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | `AbortSignal`} at
  *    {@link Context.cancellationSignal | `Context.current().cancellationSignal`} to a library that supports it.

packages/test/src/test-bundler.ts

@@ -86,7 +86,7 @@ if (RUN_INTEGRATION_TESTS) {
       }),
       {
         instanceOf: Error,
-        message: /is importing the following built-in Node modules.*dns/s,
+        message: /is importing the following disallowed modules.*dns/s,
       }
     );
   });

packages/worker/src/workflow/bundler.ts

@@ -269,15 +269,16 @@ exports.importInterceptors = function importInterceptors() {
 
             if (this.foundProblematicModules.size) {
               const err = new Error(
-                `Your Workflow code (or a library used by your Workflow code) is importing the following built-in Node modules:\n` +
+                `Your Workflow code (or a library used by your Workflow code) is importing the following disallowed modules:\n` +
                   Array.from(this.foundProblematicModules)
                     .map((module) => `  - '${module}'\n`)
                     .join('') +
-                  `Workflow code doesn't have access to built-in Node modules (in order to help enforce determinism). If you are certain ` +
-                  `these modules will not be used at runtime, then you may add their names to 'WorkerOptions.bundlerOptions.ignoreModules' in order to ` +
-                  `dismiss this warning. However, if your code execution actually depends on these modules, then you must change the code ` +
-                  `or remove the library.\n` +
-                  `See https://typescript.temporal.io/api/interfaces/worker.workeroptions/#bundleroptions for details.`
+                  `These modules can't be used in workflow context as they might break determinism.` +
+                  `HINT: Consider the following options:\n` +
+                  ` • Make sure that activity code is not imported from workflow code. Use \`import type\` to import activity function signatures.\n` +
+                  ` • Move code that has non-deterministic behaviour to activities.\n` +
+                  ` • If you know for sure that a disallowed module will not be used at runtime, add its name to 'WorkerOptions.bundlerOptions.ignoreModules' in order to dismiss this warning.\n` +
+                  `See also: https://typescript.temporal.io/api/interfaces/worker.workeroptions/#bundleroptions and https://docs.temporal.io/typescript/determinism.`
               );
 
               reject(err);