Merge pull request #222 from quixio/dev

Docs Release 2023-11-002

.github/workflows/build-commit-subfolder.yaml

@@ -107,7 +107,7 @@ jobs:
       uses: actions/checkout@v3
       with:
         repository: 'quixio/quix-streams'
-        ref: 'main' # when a dev branch exists we can get the dev content
+        ref: 'release/v0.5' # when a dev branch exists we can get the dev content
         #ref: '{{ steps.extract_branch.outputs.branch }}'
         path: 'client-library'
 

.github/workflows/sync-build-deploy.yaml

@@ -102,7 +102,7 @@ jobs:
         uses: actions/checkout@v3
         with:
           repository: 'quixio/quix-streams'
-          ref: 'main' # when a dev branch exists we can get the dev content
+          ref: 'release/v0.5' # when a dev branch exists we can get the dev content
           #ref: '{{ steps.extract_branch.outputs.branch }}'
           path: 'client-library'
 

BEST-PRACTICE.md

@@ -49,12 +49,14 @@ The Quix documentation search facility is incremental - you start typing your se
 
 Good navigation is **critical** to effective TBW. Once a reader finds themselves in the Quix documentation, they need to be able to quickly orientate themselves on the page and in the documentation set overall.
 
-The main left-hand navbar, or TOC, provides the main element of the information architecture, and is purposely organized into the following top-level hierarchy:
+The main left-hand navbar, or TOC, provides the main element of the information architecture, and is purposely organized into the following top-level hierarchy, based around the developer journey:
 
-1. **Landing page and Quickstart**. The idea here is to quickly orientate the reader. From the landing page they can jump to key pieces of documentation. The Quickstart provides an easy way to "dip a toe" into Quix, and try the product out. The Quickstart is divided into two parts: one aimed at all users, and one specifically targeting developers.
-2. **Quix Platform**. This is the main Quix product, and consists of the SaaS offering, UI, pipelines, deployments, and pre-built connectors and transforms. Concepts, How-Tos and Tutorials for Quix Platform are contained in here.
-3. **Client Library**. The Quix Streams client library provides a very effective way to write scalable real-time streaming applications. Using Quix Streams you can create solutions that work with Quix Platform, or with other services depending on your requirement. The `Client Library` section also includes API reference documentation generated from source code for both the Python and C# versions of Quix Streams.
-4. **APIs**. These are additional Quix APIs, other than those provided by Quix Streams. The documentation consists of general topics, as well as REST API references based on OAS3 documents.
+1. Get started - you're new to Quix and went to get up and running quickly.
+2. Create your project - you need to have a project to do anything in Quix.
+3. Develop your application - this is the job or service that will actually do the work.
+4. Deploy your application - you're now ready to deploy the application so it can be used.
+5. Manage your projects/pipelines - a typical event streaming app consists of a collections of services (or jobs) connected in a pipeline. 
+6. Quix Streams - the client library, as a stand-alone product it is displayed as a top level item.
 
 The longer topics can be navigated using the right-hand "on this page" TOC. This enables you to quickly navigate through the sections of a topic. It is important that topics are structured with the correct heading levels. There should only ever be one `h1` heading per topic, but there can be several `h2`s. Section headings below `h3` should be used sparingly, as they won't be displayed in the navigation, and could indicate the topic has become too convoluted. The solution can be to split the topic into multiple topics, or otherwise rethink the structure.
 
@@ -92,7 +94,7 @@ The key tooling used for the Quix documentation includes:
 
 Quix uses multiple (currently two) repositories to manage the Quix documentation, these are:
 
-1. [Quix Docs](https://github.com/quixio/quix-docs) - this is the repository for general docs, Quix Platform docs, and API docs.
+1. [Quix Docs](https://github.com/quixio/quix-docs) - this is the repository for general docs, Quix Cloud docs, and API docs.
 2. [Quix Streams](https://github.com/quixio/quix-streams) - a stand-alone repository for Quix Streams, including all Quix Streams documentation.
 
 Quix uses the MkDocs [multirepo plugin](https://github.com/jdoiro3/mkdocs-multirepo-plugin) to import a complete repo and make it part of a documentation set. Quix uses this to import the Quix Streams documentation stored in the Quix Streams repo.

WRITING-STYLE.md

@@ -33,11 +33,28 @@ Use the following guidelines regarding the company's name:
 * Possessive: Quix's technology
 * Plural: "multiple Quix deployments."
 * Quix is the name of our company
-    * Quix Portal is our product, which includes:
-        * Managed Kafka
-        * Serverless compute
-        * Quix data store
-        * APIs
+* Quix product:
+    * 'The whole thing" = Quix - one tool to build event streaming apps
+    * Components of Quix:
+        * Quix Cloud - Packaging of Quix SaaS that is fully managed and hosted on Quix owned and operated cloud infrastructure (the place where everything runs).
+        * Serverless - multi-tenant
+        * Dedicated - single-tenant
+        * Quix BYOC - Packaging of Quix SaaS designed for self-hosting on customer’s infrastructure
+        * Quix Event Streaming Application - (legacy: pipeline) a collection of applications and kafka topics that fulfill an event streaming component of an event-driven platform.
+        * Quix Kafka - Our specific installed version "flavour" of Kakfa vs Confluent Cloud (our "Confluent Integration"), Redpanda, Aiven.
+        * Quix Application: a service with a code project & a container
+        * Quix Connectors - Quix Applications that integrate data between external systems and Quix (sources, destinations)
+        * Quix Processors - Quix Applications that run code to transform data (transforms)
+        * Quix Containers - Quix Applications that act as auxiliary resources for an application
+        * Code Samples - Ready-to-run templates of code and service configuration to create your own Quix Services
+        * Quix Project - (legacy: workspace) one Git repository that contains all the code that you need to build and deploy an Event Streaming Application in multiple environments..
+
+    * CI/CD Features
+        * Quix Project Configuration - YAML files, they define workflow and setting and env variables as code. It describes your services, topics, and relations between them.
+        * Git Integration, Git (GitHub, Azure DevOps, GitLab) link to Quix Workspace.
+        * Quix Environments (staging, dev prod) - isolated infrastructure connected to a branch of your Git project
+        * Quix CLI (coming soon)
+        * Project Templates (legacy: blueprints) ungated experiences    
     * Quix Streams is our client library:
         * A client library is a collection of code specific to one programming language.
         * Quix currently offers Python and C# client libraries.

docs/apis/portal-api/setup.md

@@ -18,7 +18,7 @@ Each of these is described in the following sections.
 
 Useful information can also be found in the settings panels for your environment:
 
-1. Click `Settings` in the bottom left corner of the Quix portal.
+1. Click `Settings` in the bottom left corner of the UI.
 
 2. From `Project settings` select the environment you are working with.
 
@@ -34,7 +34,7 @@ Personal Access Tokens, or PATs, are bearer tokens that can be used to authentic
 
 To obtain a PAT, log in to Quix, and click on your profile icon in the top right corner, then click `Personal Access Tokens`. You can then generate a PAT with a lifetime suitable for your use case.
 
-Alternatively, log in to the Quix Portal, and click `Settings` in the main left-hand navigation. Then, for a specific environment, click `APIs and tokens`.
+Alternatively, log in to Quix, and click `Settings` in the main left-hand navigation. Then, for a specific environment, click `APIs and tokens`.
 
 In the `APIs and tokens` dialog, you can click `Personal Access Tokens` to generate PATs, or a Streaming Token for use with the Quix Streams client library.
 

docs/apis/query-api/raw-data.md

@@ -60,7 +60,7 @@ In reality, you’ll have far more data in the stored data, so you’ll want to
 
   - `to`
 
-Each stream you create has a unique ID. You can view the ID of a persisted via the Data section of the Quix Portal. Supply a list of stream IDs to restrict fetched data to just those streams:
+Each stream you create has a unique ID. You can view the ID of a persisted via the Data section of the UI. Supply a list of stream IDs to restrict fetched data to just those streams:
 
 ```json
 {

docs/apis/query-api/setup.md

@@ -18,7 +18,7 @@ Each of these is described in the following sections.
 
 Useful information can also be found in the settings panels for your environment:
 
-1. Click `Settings` in the bottom left corner of the Quix portal.
+1. Click `Settings` in the bottom left corner of the UI.
 
 2. From `Project settings` select the environment you are working with.
 
@@ -34,7 +34,7 @@ Personal Access Tokens, or PATs, are bearer tokens that can be used to authentic
 
 To obtain a PAT, log in to Quix, and click on your profile icon in the top right corner, then click `Personal Access Tokens`. You can then generate a PAT with a lifetime suitable for your use case.
 
-Alternatively, log in to the Quix Portal, and click `Settings` in the main left-hand navigation. Then, for a specific environment, click `APIs and tokens`.
+Alternatively, log in to Quix, and click `Settings` in the main left-hand navigation. Then, for a specific environment, click `APIs and tokens`.
 
 In the `APIs and tokens` dialog, you can click `Personal Access Tokens` to generate PATs, or a Streaming Token for use with the Quix Streams client library.
 

docs/apis/streaming-reader-api/overview.md

@@ -1,6 +1,6 @@
 # Overview
 
-As an alternative to Quix Streams, the Quix platform supports real-time data streaming over WebSockets (or Long Polling depending on client support). 
+Quix supports real-time data streaming over WebSockets (or Long Polling depending on client support). 
 
 Clients can receive updates on data and definitions for parameters and events, as they happen. 
 
@@ -9,4 +9,3 @@ Streaming Reader API is typically used by clients written in languages not suppo
 !!! note
 
     The following examples use the Microsoft [SignalR](https://docs.microsoft.com/en-us/aspnet/core/signalr/javascript-client?view=aspnetcore-5.0){target=_blank} JavaScript client library.
-

docs/apis/streaming-reader-api/setup.md

@@ -18,7 +18,7 @@ Each of these is described in the following sections.
 
 Useful information can also be found in the settings panels for your environment:
 
-1. Click `Settings` in the bottom left corner of the Quix portal.
+1. Click `Settings` in the bottom left corner of the UI.
 
 2. From `Project settings` select the environment you are working with.
 
@@ -34,7 +34,7 @@ Personal Access Tokens, or PATs, are bearer tokens that can be used to authentic
 
 To obtain a PAT, log in to Quix, and click on your profile icon in the top right corner, then click `Personal Access Tokens`. You can then generate a PAT with a lifetime suitable for your use case.
 
-Alternatively, log in to the Quix Portal, and click `Settings` in the main left-hand navigation. Then, for a specific environment, click `APIs and tokens`.
+Alternatively, log in to Quix, and click `Settings` in the main left-hand navigation. Then, for a specific environment, click `APIs and tokens`.
 
 In the `APIs and tokens` dialog, you can click `Personal Access Tokens` to generate PATs, or a Streaming Token for use with the Quix Streams client library.
 

docs/apis/streaming-writer-api/setup.md

@@ -18,7 +18,7 @@ Each of these is described in the following sections.
 
 Useful information can also be found in the settings panels for your environment:
 
-1. Click `Settings` in the bottom left corner of the Quix portal.
+1. Click `Settings` in the bottom left corner of the UI.
 
 2. From `Project settings` select the environment you are working with.
 
@@ -34,7 +34,7 @@ Personal Access Tokens, or PATs, are bearer tokens that can be used to authentic
 
 To obtain a PAT, log in to Quix, and click on your profile icon in the top right corner, then click `Personal Access Tokens`. You can then generate a PAT with a lifetime suitable for your use case.
 
-Alternatively, log in to the Quix Portal, and click `Settings` in the main left-hand navigation. Then, for a specific environment, click `APIs and tokens`.
+Alternatively, log in to Quix, and click `Settings` in the main left-hand navigation. Then, for a specific environment, click `APIs and tokens`.
 
 In the `APIs and tokens` dialog, you can click `Personal Access Tokens` to generate PATs, or a Streaming Token for use with the Quix Streams client library.
 

docs/connectors/index.md

@@ -4,6 +4,6 @@ Connectors are part of our [open source](https://github.com/quixio/quix-samples)
 
 Connectors help our users connect with other vendors such as AWS and Kafka.
 
-You can explore the connector README files here in Quix Docs. When you are ready to start using them, head over to the Quix Code Samples [GitHub](https://github.com/quixio/quix-samples){target="_blank"} repository, or [sign up](https://quix.io/signup){target="_blank"} and [login to the platform](https://portal.platform.quix.ai/){target="_blank"}.
+You can explore the connector README files here in Quix Docs. When you are ready to start using them, head over to the Quix Code Samples [GitHub](https://github.com/quixio/quix-samples){target="_blank"} repository, or [sign up](https://quix.io/signup){target="_blank"} and [log in to the platform](https://portal.platform.quix.ai/){target="_blank"}.
 
 [//]: <> (#connectors_tile_replacement)

docs/create/syncing-environment.md

@@ -8,7 +8,7 @@ You can always review the changes that will be made to your `quix.yaml` file, be
 
 The rules around manual and automatic synchronization are:
 
-1. Operations performed in the Quix portal should not cause "out of sync", as those operations are automatically saved to the Git repository. This is the case for both Quix-managed and third-party hosted Git.
+1. Operations performed in Quix should not cause "out of sync", as those operations are automatically saved to the Git repository. This is the case for both Quix-managed and third-party hosted Git.
 2. The exception to this is the case of YAML variables. When variables are created, if those are included in the `quix.yaml`, you will need to perform manual synchronization. You are prompted if this is required.
 3. If you change the `quix.yaml` in the Git repository, then you may get "out of sync". The `quix.yaml` file currently only includes topics and deployments.
 

docs/deploy/deploy-public-page.md

@@ -1,6 +1,6 @@
 # How to deploy a public service
 
-The Quix Platform enables you to deploy public-facing web pages and APIs.
+Quix enables you to deploy public-facing web pages and APIs.
 
 This how-to will help to explain the features and options and ensure projects containing public facing web pages and APIs are successful.
 

docs/deploy/environment-variables.md

@@ -1,6 +1,6 @@
-# How to add environment variables in Quix Platform
+# How to add environment variables in Quix
 
-In Quix Platform, it is possible to create new environment variables that your code can then access. This is useful for things like API keys, secrets, and passwords for other services that your code may need to access.
+In Quix, it is possible to create new environment variables that your code can then access. This is useful for things like API keys, secrets, and passwords for other services that your code may need to access.
 
 ## To create an environment variable
 

docs/develop/apis-overview.md

@@ -1,6 +1,6 @@
 # Quix APIs Overview
 
-The Quix Platform provides several APIs. These are:
+Quix provides several APIs. These are:
 
 * Streaming Writer API
 * Streaming Reader API
@@ -15,7 +15,7 @@ While [Quix Streams](../client-library-intro.md) is the main client library for
 
 In these situations Streaming Reader and Writer APIs can provide an alternative solution - for example, they can easily be accommodated in a modern web browser, or using most modern programming languages with an HTTP or SignalR client. 
 
-Portal API is useful for automating processes normally carried out manually in the Quix Portal.
+Portal API is useful for automating processes normally carried out manually in Quix.
 
 Query API is useful for testing and examining data persisted into the Quix internal database.
 
@@ -50,13 +50,13 @@ Streaming Reader uses Microsoft's [SignalR](https://learn.microsoft.com/en-us/as
 
 ## Portal API
 
-The [Portal API](../apis/portal-api/overview.md) gives access to the Quix Portal interface enabling you to automate your project deployment, management and monitoring. For example, you could build command line tools in any language with an HTTP interface available, to create, deploy, and monitor services.
+The [Portal API](../apis/portal-api/overview.md) gives access to Quix, enabling you to automate your project deployment, management and monitoring. For example, you could build command line tools in any language with an HTTP interface available, to create, deploy, and monitor services.
 
 [Read more about Portal API](../apis/portal-api/overview.md)
 
 ## Query API
 
-The [Query API](../apis/query-api/overview.md) enables you to fetch persisted data from Quix. You can use it for exploring the platform, testing, prototyping applications, or working with persisted data in any language with HTTP capabilities.
+The [Query API](../apis/query-api/overview.md) enables you to fetch persisted data from Quix. You can use it for exploring Quix, testing, prototyping applications, or working with persisted data in any language with HTTP capabilities.
 
 !!! note
 

docs/develop/authentication/personal-access-token.md

@@ -4,6 +4,6 @@ Personal Access Tokens, or PATs, are bearer tokens that can be used to authentic
 
 To obtain a PAT, log in to Quix, and click on your profile icon in the top right corner, then click `Personal Access Tokens`. You can then generate a PAT with a lifetime suitable for your use case.
 
-Alternatively, log in to the Quix Portal, and click `Settings` in the main left-hand navigation. Then, for a specific environment, click `APIs and tokens`.
+Alternatively, log in to Quix, and click `Settings` in the main left-hand navigation. Then, for a specific environment, click `APIs and tokens`.
 
 In the `APIs and tokens` dialog, you can click `Personal Access Tokens` to generate PATs, or a Streaming Token for use with the Quix Streams client library.