Suggest a standard set of terms to reduce confusion across docs #222

gewenyu99 · 2022-07-13T22:30:06Z

What Is This PR

After reviewing the new branding documents and following APA style guide, I proposed the following terms to reduce confusion across our documentation. This is not comprehensive but merely covers commonly confused terms.

Why We Need This PR

Some concepts related to Appwrite can be expressed with many different words, and phrases, and in varying formats. This is fine in conversation but can often introduce unwanted confusion.

For example, using the word "user" and "account" interchangeably to refer to:

Appwrite Console Users
Users created on the Account API
Appwrite developers (Users of Appwrite, the OSS software)
End-users of applications created on Appwrite

While there will always be confusion, we should at least make an effort to be consistent.

Other examples, Cloud Function, Function Service, Function service, and Appwrite Functions can all mean the same thing. Similarly, Server API, Admin Mode, Server-side SDK, and similar terms are used interchangeably.

Goals of This PR

During the review process, I hope to achieve the following.

Propose standard language to make our communication more clear and consistent.
Receive feedback on word choice and language; we need to be happy with the terms we choose collectively.
Receive suggestions of common confused terms I missed.

Thank you :)

README.md

gewenyu99 · 2022-07-13T22:39:42Z

README.md

+#### Authentication
+| **Term**               | **Suggested Usage.**                                                                                                                                                                                                                                          |
+|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Authentication Service | The Authentication service encompases the Account API, Users API, and Teams API.                                                                                                                                                                              |


Need Feedback

Do we want to call services

Appwrite Authentication

Authentication Service (entire proper noun, which is proper if we're consistent)

Authentication service (where Authentication, the service, is the sole proper noun)

I would vote for 2

I will post this on this week's state of the docs to get more feedback.

Should we change encompases? Feels like a complex word.

Also voting for 2. We already use that naming in console (project -> settings -> services)

What about Users Service? Since we probably call it Storage Service, Databases Service, Functions Service... Matching list of services on left side.

We should rename the button. The word Users doesn't make a ton of sense.

gewenyu99 · 2022-07-13T22:40:08Z

README.md

+| 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. |


Need Feedback

Do we want to call it a deployment of Appwrite, an instance of Appwrite? What language makes the most sense?

I think a cluster might make more sense, not 100% sure.

I will post this on this week's state of the docs to get more feedback.

eldadfux · 2022-07-14T07:44:56Z

README.md

+| 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. |


I think a cluster might make more sense, not 100% sure.

eldadfux · 2022-07-14T07:45:18Z

README.md

+| 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. |


These 3 seems very generic and not Appwrite specific

Agreed. Idk if this belongs somewhere else, but it made sense to use these correctly if we can.

Although, the Method term works here mostly to differentiate a function from our Functions service. We can remove if this is the opinion at the end of review process.

eldadfux · 2022-07-14T07:45:55Z

README.md

+#### Authentication
+| **Term**               | **Suggested Usage.**                                                                                                                                                                                                                                          |
+|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Authentication Service | The Authentication service encompases the Account API, Users API, and Teams API.                                                                                                                                                                              |


I would vote for 2

eldadfux · 2022-07-14T07:47:17Z

README.md

+| 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.                                                                   |


I think we should also mention Adapter. This one is used across Databases, Storage, Error Logging. Sometimes used for OAuth providers.

eldadfux · 2022-07-14T07:47:33Z

README.md

+| 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" |


Missing Execution

eldadfux · 2022-07-14T08:00:36Z

README.md

+|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 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.                         |


The new console will use the same terms we use for the API

Nice, we'll change this when the new console rolls out.

Meldiron

I already love this document! 😍
Left my suggestions

Meldiron · 2022-07-16T07:00:21Z

README.md


-#### Terminology
+### 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.


with many ways to express the same concepts

If I was using Appwrite and read this, it sounds negative. Like we were messy and complex, and if I want to make chat app, there are 500 ways that I need to consider.

@Meldiron I think of this as a maintainer's document. No Appwrite developer would reasonably need to read this. It's more for those who wish to contribute to Appwrite's docs, copy writing, or maybe blogs.

Meldiron · 2022-07-16T07:01:36Z

README.md

+|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 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.                                                                          |


Suggested change

| 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 | 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. |

What about Appwrite Web Console? To make sure it's clear it's the website, not terminal.

Meldiron · 2022-07-16T07:03:29Z

README.md

+| 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.|


Interesting word, pretty unique 🤔 I would say adapter or integration. Anyone else has weird vibes from the word?

This is a typo XD

We will stick with Adatper, Adaptor is technically correct in English, but I think less used. I won't dig into it further because it really doesn't matter :P

https://grammarist.com/spelling/adapter-adaptor/

Meldiron · 2022-07-16T07:06:01Z

README.md

+| 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 Cluster | Refers to a single, self-hosted deployment of Appwrite. Use as "an Appwrite Cluster" or "Appwrite Clusters".|


To me a Cluster is not only self-host but also having Appwrite scaled over many machines. Shouldn't we use the word self-host here somehow instead? That sounds more simpler, also considering we will have "selfhost" section in docs in future.

We were thinking of calling it a "self-hosted instance." Cluster is what Eldad suggested, I'll let you duke it out with Eldad, I have no particular opinion here :D

How about just Appwrite Instance and remove any references to self-hosted or cloud?

@stnguyen90 This was my original proposal XD

I agree. Cluster doesn't make sense unless we have several machines. I vote for Appwrite Instance too

Meldiron · 2022-07-16T07:07:48Z

README.md

+| 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".|
+| 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.                                                                                                                             |


We named queries as methods too (query methods being limit() or equal(). Possibly even permission methods like read() and write() in future.

This is fine. They would be in fact called methods in most textbooks.

If we want something to refer to things like account.get() rather than Query.equal() we could use API call since the SDKs make API calls to our REST APIs.

👀 I think this can work. TBH, I'm only concerned about confusing a function from the Functions Service, when we talk about this and the SDK.

Meldiron · 2022-07-16T13:08:30Z

README.md

+### 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.**                                                                                                                                                                                              |


Meldiron · 2022-07-16T13:09:27Z

README.md

+| Bucket          | Write as "a bucket" or "buckets", not a proper noun.                                                                                          |
+| File            | Write as "a file" or "files", not a proper noun.                                                                                              |
+
+#### Functions


Let's maybe add:

Variable (variables?)

Meldiron · 2022-07-16T13:24:40Z

README.md

+
+
+
+#### Database


Let's maybe add:

Permissions

Permission level

Meldiron · 2022-07-16T13:25:07Z

README.md

-#### Terminology
+### 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


Let's maybe add:

Usage stats

Audit logs

I don't have any experience with these, what terms do you suggest under them?

Meldiron · 2022-07-16T13:25:58Z

README.md


-#### Spell Checking
+#### Authentication


Let's maybe add:
-Membership

Question for you. There's a few concepts that are actually confusing right now:

Team membership vs role:member

Team roles vs role: (like role:guest)

These terms are very similar in context and meaning, but aren't the same. Should we consider definite terms for these?

CC: @eldadfux

eldadfux · 2022-07-17T05:11:22Z

I would only add that this document would also make a great blog post.

README.md

stnguyen90 · 2022-07-19T19:33:54Z

README.md

+| 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 Cluster | Refers to a single, self-hosted deployment of Appwrite. Use as "an Appwrite Cluster" or "Appwrite Clusters".|


How about just Appwrite Instance and remove any references to self-hosted or cloud?

stnguyen90 · 2022-07-19T19:36:17Z

README.md

+| 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".|
+| 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.                                                                                                                             |


If we want something to refer to things like account.get() rather than Query.equal() we could use API call since the SDKs make API calls to our REST APIs.

README.md

Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>

README.md

Vincent (Wen Yu) Ge added 3 commits July 11, 2022 22:02

add general and auth terminology

a0189d3

suggest storage and function

2998cd8

add additional terms for auth

525541a

gewenyu99 commented Jul 13, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

gewenyu99 commented Jul 13, 2022

View reviewed changes

eldadfux reviewed Jul 14, 2022

View reviewed changes

Review round 1

e639e9c

Meldiron suggested changes Jul 16, 2022

View reviewed changes

iteration after Matej's comments

6d347cf

stnguyen90 suggested changes Jul 19, 2022

View reviewed changes

gewenyu99 and others added 7 commits July 19, 2022 16:53

Update README.md

05780be

Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>

Update README.md

ac3faa4

Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>

Update README.md

baf0d38

Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>

Update README.md

b4c9994

Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>

Update README.md

8ce9004

Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>

Update README.md

0fe25e3

Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>

Update README.md

fa80c38

Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>

christyjacob4 reviewed Jul 25, 2022

View reviewed changes

README.md Outdated Show resolved Hide resolved

Aggregate suggestions

2a9a14f

gewenyu99 merged commit d35390a into update-contribution-guide Jul 27, 2022

gewenyu99 deleted the propose-terminology-guidelines branch August 4, 2022 15:56

gewenyu99 mentioned this pull request Oct 4, 2022

Databases Relationships Refactor Proposal #274

Closed

	\| 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 \| 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. \|

	\| Term \| Suggested Usage. \|
	\| Term \| Suggested Usage \|




		#### Database

Suggest a standard set of terms to reduce confusion across docs #222

Suggest a standard set of terms to reduce confusion across docs #222

Conversation

gewenyu99 commented Jul 13, 2022

What Is This PR

Why We Need This PR

Goals of This PR

Choose a reason for hiding this comment

Need Feedback

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Need Feedback

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Meldiron left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eldadfux commented Jul 17, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment