From a0189d30876070b9a8b507fdd4f189557549423f Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Mon, 11 Jul 2022 22:02:42 +0000 Subject: [PATCH 01/13] add general and auth terminology --- README.md | 58 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 41 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index c5dff5df3..cf88eb1ff 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,41 @@ -## Documentation Guidelines - -### 🚀 Contributing - -### Before Proposing Additions - -### Style Guidelines - -#### Code Examples - -#### Notices - -#### Screenshots - -#### Terminology - -#### Spell Checking +# Documentation Guidelines + +## 🚀 Contributing + +## Before Proposing Additions + +## Style Guidelines + +### Code Examples + +### Notices + +### Screenshots + +### Terminology +Appwrite has many services and features. To avoid confusion, this section suggests a standard set of terms used across Appwrite documentation to describe features and concepts. +#### General +| **Term** | **Suggested Usage.** | +|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Projects | Each Appwrite instance can have many Appwrite Projects. Use "Appwrite Projects" as a proper noun when referring to the concept, use project or projects when referring to specific projects. | +| Console | Refers to the the GUI. Can also be referred to as the "Appwrite Console" to distinguish from a Mac, Linux, or Windows machine's console. | +| Console Users | Refers to users that are registered to have access to the Appwrite Console. Not a proper noun, use as "a console user" or "the console user". Differenciate this clearly from users created through a Client SDK. | +| Client SDK | Refers to SDKs used by Web, Flutter, Android, and Apple applications. Use as a proper noun, use "a Client SDK" or "the Client SDKs", not client-side SDKs. | +| Server SDK | Refers to SDKs used by backend languages like Java, Node.js, or PHP. Use as a proper noun, use "a Server SDK" or "the Server SDKs", not server-side SDKs. | +| Developer | Refers to Appwrite developers that use Appwrite to create applications. | +| End User | Refers to end users of applications with an Appwrite backend. This doesn't refer to developers that interact with Appwrite directly. | +| Appwrite Instance | Refers to a single, self-hosted deployment of Appwrite | +| Application | Refers to the application built by the Appwrite developer. Can be referred to as web app, mobile app, flutter app, etc. | +#### Authentication +| **Term** | **Suggested Usage.** | +|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Authentication Service | The Authentication service encompases the Account API, Users API, and Teams API. | +| Account API | The Account API is an API under the Authentication service that is used by Client SDKs. Avoid "Account service" to avoid confusing developers that it is different from the "Users API" because it might imply they are separate services. | +| Users API | The User API is an API under the Authentication service that is used by Server SDKs. Avoid "Users service" to avoid confusing developers that it is accessing users different from the "Account API" because it might imply they are separate services. | +| Teams API | The Teams API is an API under the Authentication service that is used to organize created accounts. Avoid "Teams service", because it is not a stand alone service. | +| Authentication Method | An authentication method refers to ways to authenticate a user like email, phone, and JWT. Not a proper noun, avoid terms like auth method or login method. | +| OAuth2 Providers | An OAuth2 provider refers to ways to authenticate users using accounts from service providers like AWS, Facebook, or Microsoft. Avoid using simplified terms like OAuth provider and provider to avoid confusion (there are multiple types of providers now). | + +#### Database + +### Spell Checking From 2998cd82a93c062bf057c02a7e8432b5ba92ab2d Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Wed, 13 Jul 2022 21:48:21 +0000 Subject: [PATCH 02/13] suggest storage and function --- README.md | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cf88eb1ff..0e73f5d14 100644 --- a/README.md +++ b/README.md @@ -13,10 +13,11 @@ ### Screenshots ### Terminology -Appwrite has many services and features. To avoid confusion, this section suggests a standard set of terms used across Appwrite documentation to describe features and concepts. +Appwrite has many services and features with many ways to express the same concepts. To avoid confusion, this section suggests a standard set of terms used across Appwrite documentation to describe features and concepts. #### General | **Term** | **Suggested Usage.** | |---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Appwrite | Written as "Appwrite" not "AppWrite" or "appwrite". | | Projects | Each Appwrite instance can have many Appwrite Projects. Use "Appwrite Projects" as a proper noun when referring to the concept, use project or projects when referring to specific projects. | | Console | Refers to the the GUI. Can also be referred to as the "Appwrite Console" to distinguish from a Mac, Linux, or Windows machine's console. | | Console Users | Refers to users that are registered to have access to the Appwrite Console. Not a proper noun, use as "a console user" or "the console user". Differenciate this clearly from users created through a Client SDK. | @@ -26,6 +27,10 @@ Appwrite has many services and features. To avoid confusion, this section sugges | End User | Refers to end users of applications with an Appwrite backend. This doesn't refer to developers that interact with Appwrite directly. | | Appwrite Instance | Refers to a single, self-hosted deployment of Appwrite | | Application | Refers to the application built by the Appwrite developer. Can be referred to as web app, mobile app, flutter app, etc. | +| Method | Refers to SDK methods like the method `account.get()`. This helps differentiate SDK methods and Appwite Functions in written language. | +| Parameters | Refers to parameters in an SDK method or API definition. Use in cases where we speak about needs, such as "takes parameters x, y, and z" or "requires parameters x and y". | +| Arguments | Refers to arguments passed to CLI, SDK method, or REST API. Use when the argument has a concrete value and when we refer to invoking a method, such as "pass in arguments x and y, or "call account.create() with the argument "unique()" to generate a random id. | + #### Authentication | **Term** | **Suggested Usage.** | |------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -38,4 +43,31 @@ Appwrite has many services and features. To avoid confusion, this section sugges #### Database +| **Term** | **Suggested Usage.** | +|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Databases Service | Write as the "Database service" (as a proper noun). The Databases service is referred to as "Databases service", not "Database service". | +| Database | As of 0.15, the Databases service allows you to create multiple, individual databases. Use "a database" or "databases" as uncapitalized nouns, which differentiates them from the "Database service". | +| Collection | Use "collection" as a noun (no capitalization), use as "a collection" or "collections". Avoid using similar terms like "table". | +| Document | Use "document" as a noun (no capitalization), use as "a document" or "documents". Avoid using similar terms like "entry" or "row". | +| Attribute | Use "attribute" as a noun (no capitalization), use as "a attribute" or "attributes". Avoid using similar terms like "column" or "key/value". | +| Index | Use "index" as a noun (no capitalization), use as "a index" or "indexes". Use "indexes" instead of indices in a DB related context. | + +#### Storage + +| **Term** | **Suggested Usage.** | +|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------| +| Storage Service | Write as the "Storage service" (as a proper noun). | +| Bucket | Write as "a bucket" or "buckets", not a proper noun. | +| File | Write as "a file" or "files", not a proper noun. | + +#### Functions +| **Term** | **Suggested Usage.** | +|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Functions Service | Write as the "Functions service"(as a proper noun). Not "Function service" or "Cloud Functions". | +| Function (individual) | When we mention a specific function and not the service as a whole, use "a function" or "functions". Not "a cloud function" or "a Function". | +| Create | When we "create" a function, it refers to the process of using "Add Function" in console or using `functions.create()` method. No code is uploaded. | +| Deploy/Deployment | When we say we "deploy" a function or create a new deployment, this is when we upload code through the Create Deployment button or endpoint. | +| Activate Deployment | When we enable a particular version of a function, we say we "activate" the deployment. | +| Runtimes | When we refer to a runtime like `node.js 15.5`, call it a "Node.js runtime" or "function runtime". Avoid similar terms like "runtime environment" or "function environment" | + ### Spell Checking From 525541ab7e46d2fddfe225ba45a5e7a2b714ea64 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Wed, 13 Jul 2022 22:30:32 +0000 Subject: [PATCH 03/13] add additional terms for auth --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 0e73f5d14..6c470cd42 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,12 @@ Appwrite has many services and features with many ways to express the same conce | Teams API | The Teams API is an API under the Authentication service that is used to organize created accounts. Avoid "Teams service", because it is not a stand alone service. | | Authentication Method | An authentication method refers to ways to authenticate a user like email, phone, and JWT. Not a proper noun, avoid terms like auth method or login method. | | OAuth2 Providers | An OAuth2 provider refers to ways to authenticate users using accounts from service providers like AWS, Facebook, or Microsoft. Avoid using simplified terms like OAuth provider and provider to avoid confusion (there are multiple types of providers now). | +| Sign In/Log In | Verb form of creating a user session. Use "create session" where relevant, and use sign in/log in to refer to actions on a frontend application. | +| Sign Out/Log Out | Verb form of deleting a user session. Use "delete session" where relevant, and use sign out/log out to refer to actions on a frontend application. | +| Login/Signin | Noun form referring to the information used to sign in/log in. For example, "to log in, provide valid login information". | +| Register | Use "create account" where relevant, and use register/sign up to refer to actions on a frontend application. | + + #### Database From e639e9c5286df98c8c5866b76f7a5f6f55959380 Mon Sep 17 00:00:00 2001 From: Wen Yu Ge Date: Fri, 15 Jul 2022 16:55:09 -0400 Subject: [PATCH 04/13] Review round 1 --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6c470cd42..62eba2ef0 100644 --- a/README.md +++ b/README.md @@ -23,9 +23,10 @@ Appwrite has many services and features with many ways to express the same conce | Console Users | Refers to users that are registered to have access to the Appwrite Console. Not a proper noun, use as "a console user" or "the console user". Differenciate this clearly from users created through a Client SDK. | | Client SDK | Refers to SDKs used by Web, Flutter, Android, and Apple applications. Use as a proper noun, use "a Client SDK" or "the Client SDKs", not client-side SDKs. | | Server SDK | Refers to SDKs used by backend languages like Java, Node.js, or PHP. Use as a proper noun, use "a Server SDK" or "the Server SDKs", not server-side SDKs. | +| Adaptor | Refers to interfaces used to connect Appwrite with third party technologies. Adaptors are found for OAuth, Databases, Storage, and error logging. When referring to adaptors, use specific adaptor names, such as "an OAuth adaptor" or "a Storage adaptor" to avoid confusion.| | Developer | Refers to Appwrite developers that use Appwrite to create applications. | | End User | Refers to end users of applications with an Appwrite backend. This doesn't refer to developers that interact with Appwrite directly. | -| Appwrite Instance | Refers to a single, self-hosted deployment of Appwrite | +| Appwrite Cluster | Refers to a single, self-hosted deployment of Appwrite. Use as "an Appwrite Cluster" or "Appwrite Clusters".| | Application | Refers to the application built by the Appwrite developer. Can be referred to as web app, mobile app, flutter app, etc. | | Method | Refers to SDK methods like the method `account.get()`. This helps differentiate SDK methods and Appwite Functions in written language. | | Parameters | Refers to parameters in an SDK method or API definition. Use in cases where we speak about needs, such as "takes parameters x, y, and z" or "requires parameters x and y". | @@ -75,5 +76,5 @@ Appwrite has many services and features with many ways to express the same conce | Deploy/Deployment | When we say we "deploy" a function or create a new deployment, this is when we upload code through the Create Deployment button or endpoint. | | Activate Deployment | When we enable a particular version of a function, we say we "activate" the deployment. | | Runtimes | When we refer to a runtime like `node.js 15.5`, call it a "Node.js runtime" or "function runtime". Avoid similar terms like "runtime environment" or "function environment" | - +| Execution | When a function is run, triggered by an event, or triggerd by a CRON job, an "execution" is created. In documentation, refer to "running" a function as "creating an execution".| ### Spell Checking From 6d347cf3d1a0654a674d7d11bbc1694ca7a41c9d Mon Sep 17 00:00:00 2001 From: Wen Yu Ge Date: Mon, 18 Jul 2022 17:56:54 -0400 Subject: [PATCH 05/13] iteration after Matej's comments --- README.md | 40 +++++++++++++++++++++++----------------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 62eba2ef0..559504bda 100644 --- a/README.md +++ b/README.md @@ -15,15 +15,15 @@ ### Terminology Appwrite has many services and features with many ways to express the same concepts. To avoid confusion, this section suggests a standard set of terms used across Appwrite documentation to describe features and concepts. #### General -| **Term** | **Suggested Usage.** | +| **Term** | **Suggested Usage** | |---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Appwrite | Written as "Appwrite" not "AppWrite" or "appwrite". | | Projects | Each Appwrite instance can have many Appwrite Projects. Use "Appwrite Projects" as a proper noun when referring to the concept, use project or projects when referring to specific projects. | -| Console | Refers to the the GUI. Can also be referred to as the "Appwrite Console" to distinguish from a Mac, Linux, or Windows machine's console. | +| Web Console | Refers to the the web GUI. Can also be referred to as the "Appwrite Web Console" to distinguish from a Mac, Linux, or Windows machine's console or Chrome's developer console. | | Console Users | Refers to users that are registered to have access to the Appwrite Console. Not a proper noun, use as "a console user" or "the console user". Differenciate this clearly from users created through a Client SDK. | | Client SDK | Refers to SDKs used by Web, Flutter, Android, and Apple applications. Use as a proper noun, use "a Client SDK" or "the Client SDKs", not client-side SDKs. | | Server SDK | Refers to SDKs used by backend languages like Java, Node.js, or PHP. Use as a proper noun, use "a Server SDK" or "the Server SDKs", not server-side SDKs. | -| Adaptor | Refers to interfaces used to connect Appwrite with third party technologies. Adaptors are found for OAuth, Databases, Storage, and error logging. When referring to adaptors, use specific adaptor names, such as "an OAuth adaptor" or "a Storage adaptor" to avoid confusion.| +| Adapter | Refers to interfaces used to connect Appwrite with third party technologies. Adapters are found for OAuth, Databases, Storage, and error logging. When referring to adapters, use specific adapter names, such as "an Database adapter" or "a Storage adapter" to avoid confusion.| | Developer | Refers to Appwrite developers that use Appwrite to create applications. | | End User | Refers to end users of applications with an Appwrite backend. This doesn't refer to developers that interact with Appwrite directly. | | Appwrite Cluster | Refers to a single, self-hosted deployment of Appwrite. Use as "an Appwrite Cluster" or "Appwrite Clusters".| @@ -33,48 +33,54 @@ Appwrite has many services and features with many ways to express the same conce | Arguments | Refers to arguments passed to CLI, SDK method, or REST API. Use when the argument has a concrete value and when we refer to invoking a method, such as "pass in arguments x and y, or "call account.create() with the argument "unique()" to generate a random id. | #### Authentication -| **Term** | **Suggested Usage.** | +| **Term** | **Suggested Usage** | |------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Authentication Service | The Authentication service encompases the Account API, Users API, and Teams API. | -| Account API | The Account API is an API under the Authentication service that is used by Client SDKs. Avoid "Account service" to avoid confusing developers that it is different from the "Users API" because it might imply they are separate services. | -| Users API | The User API is an API under the Authentication service that is used by Server SDKs. Avoid "Users service" to avoid confusing developers that it is accessing users different from the "Account API" because it might imply they are separate services. | -| Teams API | The Teams API is an API under the Authentication service that is used to organize created accounts. Avoid "Teams service", because it is not a stand alone service. | +| Authentication Service | The Authentication Service is composed of the Account API, Users API, and Teams API. | +| Account API | The Account API is an API under the Authentication Service that is used by Client SDKs. Avoid "Account Service" to avoid confusing developers that it is different from the "Users API" because it might imply they are separate services. | +| Users API | The User API is an API under the Authentication Service that is used by Server SDKs. Avoid "Users Service" to avoid confusing developers that it is accessing users different from the "Account API" because it might imply they are separate services. | +| Teams API | The Teams API is an API under the Authentication Service that is used to organize created accounts. Avoid "Teams Service", because it is not a stand alone service. | | Authentication Method | An authentication method refers to ways to authenticate a user like email, phone, and JWT. Not a proper noun, avoid terms like auth method or login method. | -| OAuth2 Providers | An OAuth2 provider refers to ways to authenticate users using accounts from service providers like AWS, Facebook, or Microsoft. Avoid using simplified terms like OAuth provider and provider to avoid confusion (there are multiple types of providers now). | +| OAuth2 Providers | An OAuth2 provider refers to ways to authenticate users using accounts from service providers like GitHub or Google. Avoid using simplified terms like OAuth provider and provider to avoid confusion (there are multiple types of providers now). | | Sign In/Log In | Verb form of creating a user session. Use "create session" where relevant, and use sign in/log in to refer to actions on a frontend application. | | Sign Out/Log Out | Verb form of deleting a user session. Use "delete session" where relevant, and use sign out/log out to refer to actions on a frontend application. | | Login/Signin | Noun form referring to the information used to sign in/log in. For example, "to log in, provide valid login information". | | Register | Use "create account" where relevant, and use register/sign up to refer to actions on a frontend application. | - +| Roles | Use "role" to describe the authentication status of a user request, such as `role:all`, `role:guest`, and `role:member`.| +| Membership | Use "Membership" to express the relationship where a account belongs to a group or a team. Each memebership entity has defined team roles| +| Team Role | Use "team role" to describe the arbitrary roles defined in each team memebership entity.| + #### Database -| **Term** | **Suggested Usage.** | +| **Term** | **Suggested Usage** | |-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Databases Service | Write as the "Database service" (as a proper noun). The Databases service is referred to as "Databases service", not "Database service". | -| Database | As of 0.15, the Databases service allows you to create multiple, individual databases. Use "a database" or "databases" as uncapitalized nouns, which differentiates them from the "Database service". | +| Databases Service | Write as the "Database Service" (as a proper noun). The Databases Service is referred to as "Databases Service", not "Database Service". | +| Database | As of 0.15, the Databases Service allows you to create multiple, individual databases. Use "a database" or "databases" as uncapitalized nouns, which differentiates them from the "Database Service". | | Collection | Use "collection" as a noun (no capitalization), use as "a collection" or "collections". Avoid using similar terms like "table". | | Document | Use "document" as a noun (no capitalization), use as "a document" or "documents". Avoid using similar terms like "entry" or "row". | | Attribute | Use "attribute" as a noun (no capitalization), use as "a attribute" or "attributes". Avoid using similar terms like "column" or "key/value". | | Index | Use "index" as a noun (no capitalization), use as "a index" or "indexes". Use "indexes" instead of indices in a DB related context. | +| Permissions | Use "Permissions" to describe the definition of read and write access to a resource. The definition is by User ID, Team ID, or Role. | +| Permission Level | Use "Permission Level" to describe the scope of defined permissions. Permission can be defined per resource (for each file) or per group of resource (for each file in a bucket).| #### Storage -| **Term** | **Suggested Usage.** | +| **Term** | **Suggested Usage** | |-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------| -| Storage Service | Write as the "Storage service" (as a proper noun). | +| Storage Service | Write as the "Storage Service" (as a proper noun). | | Bucket | Write as "a bucket" or "buckets", not a proper noun. | | File | Write as "a file" or "files", not a proper noun. | #### Functions -| **Term** | **Suggested Usage.** | +| **Term** | **Suggested Usage** | |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Functions Service | Write as the "Functions service"(as a proper noun). Not "Function service" or "Cloud Functions". | +| Functions Service | Write as the "Functions Service"(as a proper noun). Not "Function Service" or "Cloud Functions". | | Function (individual) | When we mention a specific function and not the service as a whole, use "a function" or "functions". Not "a cloud function" or "a Function". | | Create | When we "create" a function, it refers to the process of using "Add Function" in console or using `functions.create()` method. No code is uploaded. | | Deploy/Deployment | When we say we "deploy" a function or create a new deployment, this is when we upload code through the Create Deployment button or endpoint. | | Activate Deployment | When we enable a particular version of a function, we say we "activate" the deployment. | | Runtimes | When we refer to a runtime like `node.js 15.5`, call it a "Node.js runtime" or "function runtime". Avoid similar terms like "runtime environment" or "function environment" | | Execution | When a function is run, triggered by an event, or triggerd by a CRON job, an "execution" is created. In documentation, refer to "running" a function as "creating an execution".| +| Variables | When a function is run, a set of variables are passed in through the `req` object. Some are generated by the runtime, some are defined under the settigs of a function. These are referred to as "variables" and not "environment variables".| ### Spell Checking From 05780be9b7f0ea678cefd8a63ab1bcf0471b82fe Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 19 Jul 2022 16:53:36 -0400 Subject: [PATCH 06/13] Update README.md Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 559504bda..4360f7681 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Appwrite has many services and features with many ways to express the same conce #### General | **Term** | **Suggested Usage** | |---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Appwrite | Written as "Appwrite" not "AppWrite" or "appwrite". | +| Appwrite | Written as "Appwrite" rather than "AppWrite" or "appwrite". | | Projects | Each Appwrite instance can have many Appwrite Projects. Use "Appwrite Projects" as a proper noun when referring to the concept, use project or projects when referring to specific projects. | | Web Console | Refers to the the web GUI. Can also be referred to as the "Appwrite Web Console" to distinguish from a Mac, Linux, or Windows machine's console or Chrome's developer console. | | Console Users | Refers to users that are registered to have access to the Appwrite Console. Not a proper noun, use as "a console user" or "the console user". Differenciate this clearly from users created through a Client SDK. | From ac3faa47af5859165ad961f3fffd79da8505af5a Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 19 Jul 2022 16:53:56 -0400 Subject: [PATCH 07/13] Update README.md Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4360f7681..c7b97a2cf 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Appwrite has many services and features with many ways to express the same conce | Console Users | Refers to users that are registered to have access to the Appwrite Console. Not a proper noun, use as "a console user" or "the console user". Differenciate this clearly from users created through a Client SDK. | | Client SDK | Refers to SDKs used by Web, Flutter, Android, and Apple applications. Use as a proper noun, use "a Client SDK" or "the Client SDKs", not client-side SDKs. | | Server SDK | Refers to SDKs used by backend languages like Java, Node.js, or PHP. Use as a proper noun, use "a Server SDK" or "the Server SDKs", not server-side SDKs. | -| Adapter | Refers to interfaces used to connect Appwrite with third party technologies. Adapters are found for OAuth, Databases, Storage, and error logging. When referring to adapters, use specific adapter names, such as "an Database adapter" or "a Storage adapter" to avoid confusion.| +| Adapter | Refers to interfaces used to connect Appwrite with third party technologies. Adapters are found for OAuth, Databases, Storage, and error logging. When referring to adapters, use specific adapter names, such as "a Database adapter" or "a Storage adapter" to avoid confusion.| | Developer | Refers to Appwrite developers that use Appwrite to create applications. | | End User | Refers to end users of applications with an Appwrite backend. This doesn't refer to developers that interact with Appwrite directly. | | Appwrite Cluster | Refers to a single, self-hosted deployment of Appwrite. Use as "an Appwrite Cluster" or "Appwrite Clusters".| From baf0d3804212c481ddd9b6aa076901c4fead9e28 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 19 Jul 2022 16:54:35 -0400 Subject: [PATCH 08/13] Update README.md Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c7b97a2cf..75c5fec52 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Appwrite has many services and features with many ways to express the same conce |------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Authentication Service | The Authentication Service is composed of the Account API, Users API, and Teams API. | | Account API | The Account API is an API under the Authentication Service that is used by Client SDKs. Avoid "Account Service" to avoid confusing developers that it is different from the "Users API" because it might imply they are separate services. | -| Users API | The User API is an API under the Authentication Service that is used by Server SDKs. Avoid "Users Service" to avoid confusing developers that it is accessing users different from the "Account API" because it might imply they are separate services. | +| Users API | The Users API is an API under the Authentication Service that is used by Server SDKs. Avoid "Users Service" to avoid confusing developers that it is accessing users different from the "Account API" because it might imply they are separate services. | | Teams API | The Teams API is an API under the Authentication Service that is used to organize created accounts. Avoid "Teams Service", because it is not a stand alone service. | | Authentication Method | An authentication method refers to ways to authenticate a user like email, phone, and JWT. Not a proper noun, avoid terms like auth method or login method. | | OAuth2 Providers | An OAuth2 provider refers to ways to authenticate users using accounts from service providers like GitHub or Google. Avoid using simplified terms like OAuth provider and provider to avoid confusion (there are multiple types of providers now). | From b4c999468638ddee636d4df38d610a6b5ac081ec Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 19 Jul 2022 16:54:46 -0400 Subject: [PATCH 09/13] Update README.md Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 75c5fec52..d24bb4a30 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ Appwrite has many services and features with many ways to express the same conce | **Term** | **Suggested Usage** | |-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Databases Service | Write as the "Database Service" (as a proper noun). The Databases Service is referred to as "Databases Service", not "Database Service". | +| Databases Service | Write as the "Database Service" (as a proper noun). The Databases Service is referred to as "Databases Service" rather than "Database Service". | | Database | As of 0.15, the Databases Service allows you to create multiple, individual databases. Use "a database" or "databases" as uncapitalized nouns, which differentiates them from the "Database Service". | | Collection | Use "collection" as a noun (no capitalization), use as "a collection" or "collections". Avoid using similar terms like "table". | | Document | Use "document" as a noun (no capitalization), use as "a document" or "documents". Avoid using similar terms like "entry" or "row". | From 8ce900476301e201021a2e8a6ceb482916f65b59 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 19 Jul 2022 16:54:55 -0400 Subject: [PATCH 10/13] Update README.md Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d24bb4a30..72f161e03 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ Appwrite has many services and features with many ways to express the same conce #### Functions | **Term** | **Suggested Usage** | |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Functions Service | Write as the "Functions Service"(as a proper noun). Not "Function Service" or "Cloud Functions". | +| Functions Service | Write as the "Functions Service" (as a proper noun) rather than "Function Service" or "Cloud Functions". | | Function (individual) | When we mention a specific function and not the service as a whole, use "a function" or "functions". Not "a cloud function" or "a Function". | | Create | When we "create" a function, it refers to the process of using "Add Function" in console or using `functions.create()` method. No code is uploaded. | | Deploy/Deployment | When we say we "deploy" a function or create a new deployment, this is when we upload code through the Create Deployment button or endpoint. | From 0fe25e33bbe741a889da3f07584e156630c3f869 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 19 Jul 2022 16:55:02 -0400 Subject: [PATCH 11/13] Update README.md Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 72f161e03..8d77e5d66 100644 --- a/README.md +++ b/README.md @@ -82,5 +82,5 @@ Appwrite has many services and features with many ways to express the same conce | Activate Deployment | When we enable a particular version of a function, we say we "activate" the deployment. | | Runtimes | When we refer to a runtime like `node.js 15.5`, call it a "Node.js runtime" or "function runtime". Avoid similar terms like "runtime environment" or "function environment" | | Execution | When a function is run, triggered by an event, or triggerd by a CRON job, an "execution" is created. In documentation, refer to "running" a function as "creating an execution".| -| Variables | When a function is run, a set of variables are passed in through the `req` object. Some are generated by the runtime, some are defined under the settigs of a function. These are referred to as "variables" and not "environment variables".| +| Variables | When a function is run, a set of variables are passed in through the `req` object. Some are generated by the runtime, some are defined under the settings of a function. These are referred to as "variables" rather than "environment variables".| ### Spell Checking From fa80c381b6e82cde7dab23e9a0c67ef604189523 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 19 Jul 2022 16:55:12 -0400 Subject: [PATCH 12/13] Update README.md Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8d77e5d66..9ecbf3f4a 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ Appwrite has many services and features with many ways to express the same conce | **Term** | **Suggested Usage** | |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Functions Service | Write as the "Functions Service" (as a proper noun) rather than "Function Service" or "Cloud Functions". | -| Function (individual) | When we mention a specific function and not the service as a whole, use "a function" or "functions". Not "a cloud function" or "a Function". | +| Function (individual) | When we mention a specific function and not the service as a whole, use "a function" or "functions" rather than "a cloud function" or "a Function". | | Create | When we "create" a function, it refers to the process of using "Add Function" in console or using `functions.create()` method. No code is uploaded. | | Deploy/Deployment | When we say we "deploy" a function or create a new deployment, this is when we upload code through the Create Deployment button or endpoint. | | Activate Deployment | When we enable a particular version of a function, we say we "activate" the deployment. | From 2a9a14f304482197b1ff58db08c2d0c671ac58ce Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Wed, 27 Jul 2022 20:52:47 +0000 Subject: [PATCH 13/13] Aggregate suggestions --- README.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 9ecbf3f4a..761e7c6ff 100644 --- a/README.md +++ b/README.md @@ -13,24 +13,25 @@ ### Screenshots ### Terminology -Appwrite has many services and features with many ways to express the same concepts. To avoid confusion, this section suggests a standard set of terms used across Appwrite documentation to describe features and concepts. +Appwrite has many services and features. Our word choices must be consistent across the many documentation pages to communicate clearly and precisely. + #### General | **Term** | **Suggested Usage** | |---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Appwrite | Written as "Appwrite" rather than "AppWrite" or "appwrite". | | Projects | Each Appwrite instance can have many Appwrite Projects. Use "Appwrite Projects" as a proper noun when referring to the concept, use project or projects when referring to specific projects. | -| Web Console | Refers to the the web GUI. Can also be referred to as the "Appwrite Web Console" to distinguish from a Mac, Linux, or Windows machine's console or Chrome's developer console. | -| Console Users | Refers to users that are registered to have access to the Appwrite Console. Not a proper noun, use as "a console user" or "the console user". Differenciate this clearly from users created through a Client SDK. | +| Appwrite Dashboard | Refers to the the web GUI. Can be referred to as "dashboard" in short, when contextual confusion is not a problem. | +| Dashboard Users | Refers to users that are registered to have access to the Appwrite Dashboard. Not a proper noun, use as "a dashboard user" or "the dashboard user". Differenciate this clearly from users created through a Client SDK. | | Client SDK | Refers to SDKs used by Web, Flutter, Android, and Apple applications. Use as a proper noun, use "a Client SDK" or "the Client SDKs", not client-side SDKs. | | Server SDK | Refers to SDKs used by backend languages like Java, Node.js, or PHP. Use as a proper noun, use "a Server SDK" or "the Server SDKs", not server-side SDKs. | | Adapter | Refers to interfaces used to connect Appwrite with third party technologies. Adapters are found for OAuth, Databases, Storage, and error logging. When referring to adapters, use specific adapter names, such as "a Database adapter" or "a Storage adapter" to avoid confusion.| | Developer | Refers to Appwrite developers that use Appwrite to create applications. | | End User | Refers to end users of applications with an Appwrite backend. This doesn't refer to developers that interact with Appwrite directly. | -| Appwrite Cluster | Refers to a single, self-hosted deployment of Appwrite. Use as "an Appwrite Cluster" or "Appwrite Clusters".| +| Appwrite Instance | Refers to a single, self-hosted deployment of Appwrite. Use as "an Appwrite instance" or "Appwrite instances".| | Application | Refers to the application built by the Appwrite developer. Can be referred to as web app, mobile app, flutter app, etc. | -| Method | Refers to SDK methods like the method `account.get()`. This helps differentiate SDK methods and Appwite Functions in written language. | -| Parameters | Refers to parameters in an SDK method or API definition. Use in cases where we speak about needs, such as "takes parameters x, y, and z" or "requires parameters x and y". | -| Arguments | Refers to arguments passed to CLI, SDK method, or REST API. Use when the argument has a concrete value and when we refer to invoking a method, such as "pass in arguments x and y, or "call account.create() with the argument "unique()" to generate a random id. | +| Usage Stats | Refers to the analytics collected for select services and displayed on the Appwrite Dashboard. | +| Audit Logs | Refers to the trail of logs displayed for select services that show what changes have been made and who made them. | + #### Authentication | **Term** | **Suggested Usage** | @@ -77,7 +78,7 @@ Appwrite has many services and features with many ways to express the same conce |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Functions Service | Write as the "Functions Service" (as a proper noun) rather than "Function Service" or "Cloud Functions". | | Function (individual) | When we mention a specific function and not the service as a whole, use "a function" or "functions" rather than "a cloud function" or "a Function". | -| Create | When we "create" a function, it refers to the process of using "Add Function" in console or using `functions.create()` method. No code is uploaded. | +| Create | When we "create" a function, it refers to the process of using "Add Function" on the dashboard or using `functions.create()` method. No code is uploaded. | | Deploy/Deployment | When we say we "deploy" a function or create a new deployment, this is when we upload code through the Create Deployment button or endpoint. | | Activate Deployment | When we enable a particular version of a function, we say we "activate" the deployment. | | Runtimes | When we refer to a runtime like `node.js 15.5`, call it a "Node.js runtime" or "function runtime". Avoid similar terms like "runtime environment" or "function environment" |