docs: Improve comments and docs for welcoming helix.ts

Signed-off-by: Loïc Saint-Roch <[email protected]>

README.md

@@ -3,41 +3,34 @@
 [![GitHub Release](https://img.shields.io/github/v/release/nunchistudio/helix)](https://github.com/nunchistudio/helix/releases/latest)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-helix is how I build and maintain reliable, cloud-native, high-performance (micro)
-services. After years of working with different organizations and various technical
-stacks, I've decided to put my knowledge and experiences into helix, so I can
-deliver a consistent and high quality of work. I hope it makes your development
-a little bit easier!
-
-helix acts as a library you can import in your code. Implementations:
-- [Go](https://github.com/nunchistudio/helix.go)
+helix is a framework for building cloud-native, consistent, reliable, and
+high-performance (micro) services. It allows back-end engineers to simplify
+development of complex problems through a thin layer of abstraction that handles
+automatic logging, tracing, observability, and event propagation across services
+and integrations.
+
+helix acts as a package you can import in your code. Implementations:
+- [Go](https://github.com/nunchistudio/helix.go): for building micro-services
+  with all the benefits listed above.
+- [TypeScript](https://github.com/nunchistudio/helix.ts): for consuming public
+  types on the front-end exposed by micro-services.
 
 ## Use cases
 
 helix was developed with the following use cases in mind:
 
-- Consistent and high-performance (micro) services;
-- Effortless end-to-end observability and event propagation across services.
-
-## Goals
+- Engineers must be able to write and maintain cloud-native, consistent, reliable,
+  and high-performance (micro) services with no hassle.
+- Engineers must have the power to transparently leverage end-to-end observability
+  and event propagation across services and integrations.
+- Engineering and product teams must be able to understand the user journey, fix
+  customer issues, and improve user/platform/product experience together via
+  end-to-end observability.
+- Engineers must focus on the business logic. Technical challenges such as
+  consistency and observability must live outside the business logic of the
+  services.
 
-helix was developed with the following goals in mind:
-
-- The solution must be deployable anywhere and everywhere.
-- The solution must be easy to configure and operate.
-- The solution could exist in any and every language.
-- The solution must allow smooth onboarding and no lock-in.
-- The solution must provide a transparent layer of abstraction for end-to-end
-  observability.
-- The solution must be as light as possible, while still supporting out of the
-  box capabilities via integrations.
-  - Integrations capabilities must not overlap with one another.
-  - Integrations must be implemented in all languages supported. 
-  - Integrations must be as consistent as possible across languages.
-  - Integrations internal lifecycle must not be exposed to end-users.
-  - Configuration across integrations must be as easy and consistent as possible.
-  - Custom integrations must be possible in case built-in ones don't fit the
-    requirements of a company.
+![Event propagation with helix](https://nunchi.studio/helix/screenshots/trace-distributed.png)
 
 ## Features and benefits
 
@@ -62,11 +55,25 @@ across services and integrations.
   in the REST router for request/response validation against an OpenAPI description,
   or in other integrations for message validation against an AsyncAPI description.
 
-By using helix, organizations can benefit from automatic distributed tracing,
-error recording, and event propagation across their stack with no additional
-lines of code! This highly improves developer experience and velocity.
+## Goals
+
+To understand why helix is designed this way, it's important to understand the
+following goals in mind:
 
-![Event propagation with helix](./assets/screenshots/trace-distributed.png)
+- The solution must be deployable anywhere and everywhere.
+- The solution must be easy to configure and operate.
+- The solution could exist in any and every language.
+- The solution must allow smooth onboarding and no lock-in.
+- The solution must provide a transparent layer of abstraction for end-to-end
+  observability.
+- The solution must be as light as possible, while still supporting out of the
+  box capabilities via integrations.
+  - Integrations capabilities must not overlap with one another.
+  - Integrations must be as consistent as possible across languages.
+  - Integrations internal lifecycle must not be exposed to end-users.
+  - Configuration across integrations must be as easy and consistent as possible.
+  - Custom integrations must be possible in case built-in ones don't fit the
+    requirements of a company.
 
 ## License
 

documentation/event-propagation.md

@@ -19,9 +19,15 @@ no additional development required on the application.
   within your own network, then this caveat may not apply.
 {% /callout %}
 
-{% tab name="Go" %}
-  {% partial file="helix-go/event-propagation.md" /%} 
-{% /tab %}
+{% tabs %}
+  {% tab name="Go" %}
+    {% partial file="helix-go/event-propagation.md" /%} 
+  {% /tab %}
+
+  {% tab name="TypeScript" %}
+    {% partial file="helix-ts/event-propagation.md" /%} 
+  {% /tab %}
+{% /tabs %}
 
 By having a consistent event propagation across all services and integrations, an
 organization can benefit end-to-end observability much more easily:

documentation/from-zero-to-hero.md

@@ -6,15 +6,14 @@ title: "From zero to hero in 20′"
 # {% $markdoc.frontmatter.title %}
 
 In this tutorial we will setup a local OpenTelemetry stack for helix services.
-Then, we will create our first helix service: a HTTP API exposing a single endpoint.
-Finally, we will create a second helix service, with a publish/subscribe mechanism
-between the two services.
+Then, we will create our first helix service in Go: a HTTP API exposing a single
+endpoint. Finally, we will create a second helix service, with a publish/subscribe
+mechanism between the two services.
 
-At the end, you will be able to see how easy it is to use helix and how helix
-can automate most of your counterproductive tasks when working with multiple
-services.
+At the end, you will be able to see how easy it is to use helix and how helix can
+automate most of your counterproductive tasks when working with multiple services.
 
-{% callout level="success" iconType="launch" title="TLDR; Source code is on GitHub" %}
+{% callout level="success" iconType="bullseye" title="TLDR; Source code is on GitHub" %}
   Source code of this guide is available in the [`platform-starter` repository
   on GitHub](https://github.com/nunchistudio/platform-starter).
 {% /callout %}
@@ -85,7 +84,7 @@ If you followed the local setup above, you should run:
 $ export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=localhost:7021
 ```
 
-{% callout level="warning" iconType="warning" title="Warning" %}
+{% callout level="warning" iconType="alert" title="Warning" %}
   If the environment variable is not available from a service, traces will not be
   exported/collected. If this is the case you should see an error like this one
   (truncated for better visibility):
@@ -98,9 +97,11 @@ Now that you're all set with an OpenTelemetry stack, you can write your first
 helix service. This service will expose a HTTP endpoint on `POST /anything`,
 using the [REST router integration](/helix/integration/rest).
 
-{% tab name="Go" %}
-  {% partial file="helix-go/from-zero-to-hero-first.md" /%} 
-{% /tab %}
+{% tabs %}
+  {% tab name="Go" %}
+    {% partial file="helix-go/from-zero-to-hero-first.md" /%} 
+  {% /tab %}
+{% /tabs %}
 
 You now have a helix service up and running, exposing a HTTP API on
 `http://localhost:8080`. Let's try to request the `POST /anything` endpoint:
@@ -146,9 +147,11 @@ $ docker run -d -p 4222:4222 nats -js
 The `httpapi` service will publish a message via NATS JetStream on each and every
 HTTP requests made against the endpoint created earlier.
 
-{% tab name="Go" %}
-  {% partial file="helix-go/from-zero-to-hero-publish.md" /%} 
-{% /tab %}
+{% tabs %}
+  {% tab name="Go" %}
+    {% partial file="helix-go/from-zero-to-hero-publish.md" /%} 
+  {% /tab %}
+{% /tabs %}
 
 ### Your second service
 
@@ -157,9 +160,11 @@ NATS JetStream subject and receive all messages of the said subject. In this
 demo, all messages received will come from the HTTP endpoint of the `httpapi`
 service.
 
-{% tab name="Go" %}
-  {% partial file="helix-go/from-zero-to-hero-second.md" /%} 
-{% /tab %}
+{% tabs %}
+  {% tab name="Go" %}
+    {% partial file="helix-go/from-zero-to-hero-second.md" /%} 
+  {% /tab %}
+{% /tabs %}
 
 ### Event propagation in action
 
@@ -203,6 +208,6 @@ such as the queue and subject.
 To go a bit further with this example and discover helix step-by-step, you could:
 - Enable and configure OpenAPI validation for the REST router in the `httpapi`
   service;
-- Add another integration in the `subscriber` service (like PostgreSQL);
+- Add another integration in the `subscriber` service (such as PostgreSQL);
 - Run both services in Docker containers to explore logs using the Loki datasource
   in Grafana.

documentation/index.md

@@ -5,41 +5,34 @@ title: "What is helix?"
 
 # {% $markdoc.frontmatter.title %}
 
-helix is how I build and maintain reliable, cloud-native, high-performance (micro)
-services. After years of working with different organizations and various technical
-stacks, I've decided to put my knowledge and experiences into helix, so I can
-deliver a consistent and high quality of work. I hope it makes your development
-a little bit easier!
+helix is a framework for building cloud-native, consistent, reliable, and
+high-performance (micro) services. It allows back-end engineers to simplify
+development of complex problems through a thin layer of abstraction that handles
+automatic logging, tracing, observability, and event propagation across services
+and integrations.
 
-helix acts as a library you can import in your code. Implementations:
-- [Go](https://github.com/nunchistudio/helix.go)
+helix acts as a package you can import in your code. Implementations:
+- [Go](https://github.com/nunchistudio/helix.go): for building micro-services
+  with all the benefits listed above.
+- [TypeScript](https://github.com/nunchistudio/helix.ts): for consuming public
+  types on the front-end exposed by micro-services.
 
 ## Use cases
 
 helix was developed with the following use cases in mind:
 
-- Consistent and high-performance (micro) services;
-- Effortless end-to-end observability and event propagation across services.
+- Engineers must be able to write and maintain cloud-native, consistent, reliable,
+  and high-performance (micro) services with no hassle.
+- Engineers must have the power to transparently leverage end-to-end observability
+  and event propagation across services and integrations.
+- Engineering and product teams must be able to understand the user journey, fix
+  customer issues, and improve user/platform/product experience together via
+  end-to-end observability.
+- Engineers must focus on the business logic. Technical challenges such as
+  consistency and observability must live outside the business logic of the
+  services.
 
-## Goals
-
-helix was developed with the following goals in mind:
-
-- The solution must be deployable anywhere and everywhere.
-- The solution must be easy to configure and operate.
-- The solution could exist in any and every language.
-- The solution must allow smooth onboarding and no lock-in.
-- The solution must provide a transparent layer of abstraction for end-to-end
-  observability.
-- The solution must be as light as possible, while still supporting out of the
-  box capabilities via integrations.
-  - Integrations capabilities must not overlap with one another.
-  - Integrations must be implemented in all languages supported. 
-  - Integrations must be as consistent as possible across languages.
-  - Integrations internal lifecycle must not be exposed to end-users.
-  - Configuration across integrations must be as easy and consistent as possible.
-  - Custom integrations must be possible in case built-in ones don't fit the
-    requirements of a company.
+![Event propagation with helix](https://nunchi.studio/helix/screenshots/trace-distributed.png)
 
 ## Features and benefits
 
@@ -64,8 +57,22 @@ across services and integrations.
   in the REST router for request/response validation against an OpenAPI description,
   or in other integrations for message validation against an AsyncAPI description.
 
-By using helix, organizations can benefit from automatic distributed tracing,
-error recording, and event propagation across their stack with no additional
-lines of code! This highly improves developer experience and velocity.
+## Goals
+
+To understand why helix is designed this way, it's important to understand the
+following goals in mind:
 
-![Event propagation with helix](/helix/screenshots/trace-distributed.png)
+- The solution must be deployable anywhere and everywhere.
+- The solution must be easy to configure and operate.
+- The solution could exist in any and every language.
+- The solution must allow smooth onboarding and no lock-in.
+- The solution must provide a transparent layer of abstraction for end-to-end
+  observability.
+- The solution must be as light as possible, while still supporting out of the
+  box capabilities via integrations.
+  - Integrations capabilities must not overlap with one another.
+  - Integrations must be as consistent as possible across languages.
+  - Integrations internal lifecycle must not be exposed to end-users.
+  - Configuration across integrations must be as easy and consistent as possible.
+  - Custom integrations must be possible in case built-in ones don't fit the
+    requirements of a company.

documentation/integration/bucket.md

@@ -38,6 +38,8 @@ span.kind: "client"
 
 ## Usage
 
-{% tab name="Go" %}
-  {% partial file="helix-go/integration/bucket.md" /%} 
-{% /tab %}
+{% tabs %}
+  {% tab name="Go" %}
+    {% partial file="helix-go/integration/bucket.md" /%} 
+  {% /tab %}
+{% /tabs %}

documentation/integration/clickhouse.md

@@ -27,6 +27,8 @@ span.kind: "server"
 
 ## Usage
 
-{% tab name="Go" %}
-  {% partial file="helix-go/integration/clickhouse.md" /%} 
-{% /tab %}
+{% tabs %}
+  {% tab name="Go" %}
+    {% partial file="helix-go/integration/clickhouse.md" /%} 
+  {% /tab %}
+{% /tabs %}

documentation/integration/nats.md

@@ -36,6 +36,8 @@ span.kind: "consumer"
 
 ## Usage
 
-{% tab name="Go" %}
-  {% partial file="helix-go/integration/nats.md" /%} 
-{% /tab %}
+{% tabs %}
+  {% tab name="Go" %}
+    {% partial file="helix-go/integration/nats.md" /%} 
+  {% /tab %}
+{% /tabs %}

documentation/integration/openfeature.md

@@ -32,6 +32,8 @@ openfeature.value: "blue"
 
 ## Usage
 
-{% tab name="Go" %}
-  {% partial file="helix-go/integration/openfeature.md" /%} 
-{% /tab %}
+{% tabs %}
+  {% tab name="Go" %}
+    {% partial file="helix-go/integration/openfeature.md" /%} 
+  {% /tab %}
+{% /tabs %}

documentation/integration/postgres.md

@@ -38,6 +38,8 @@ span.kind: "server"
 
 ## Usage
 
-{% tab name="Go" %}
-  {% partial file="helix-go/integration/postgres.md" /%} 
-{% /tab %}
+{% tabs %}
+  {% tab name="Go" %}
+    {% partial file="helix-go/integration/postgres.md" /%} 
+  {% /tab %}
+{% /tabs %}

documentation/integration/rest.md

@@ -69,6 +69,12 @@ the health check would be:
 
 ## Usage
 
-{% tab name="Go" %}
-  {% partial file="helix-go/integration/rest.md" /%} 
-{% /tab %}
+{% tabs %}
+  {% tab name="Go" %}
+    {% partial file="helix-go/integration/rest.md" /%} 
+  {% /tab %}
+
+  {% tab name="TypeScript" %}
+    {% partial file="helix-ts/integration/rest.md" /%} 
+  {% /tab %}
+{% /tabs %}

documentation/integration/temporal.md

@@ -42,6 +42,8 @@ span.kind: "internal"
 
 ## Usage
 
-{% tab name="Go" %}
-  {% partial file="helix-go/integration/temporal.md" /%} 
-{% /tab %}
+{% tabs %}
+  {% tab name="Go" %}
+    {% partial file="helix-go/integration/temporal.md" /%} 
+  {% /tab %}
+{% /tabs %}

documentation/integration/vault.md

@@ -32,6 +32,8 @@ span.kind: "internal"
 
 ## Usage
 
-{% tab name="Go" %}
-  {% partial file="helix-go/integration/vault.md" /%} 
-{% /tab %}
+{% tabs %}
+  {% tab name="Go" %}
+    {% partial file="helix-go/integration/vault.md" /%} 
+  {% /tab %}
+{% /tabs %}