+ 
+ 
+ 
+ +Learn more about environment variables +
+``` + +### Referencing UI Elements +When referencing buttons, tabs, and other interactive UI elements, use the full text found on the UI element in bold. For example **Create Project** or **Add Platform**. + +When referencing example copy text that appears or could appear on a piece of UI, use double quotes. For example, for each function listed in the **Functions** tab, you will see the runtime used by that function, such as "Dart 2.16" or "Node.js 16.0". + +### Verbatim References Inline +Monospace font inline through the use of `| + | Provider | ++ |
|---|---|---|
|
+
+
+ |
+ + DigitalOcean + | ++ Click to Install + | +
|
+
+
+ |
+ + Gitpod + | ++ Click to Install + | +
#ruby code here...// node code here...//php code here..` tags.
+
+The following will render correctly:
+```html
+
+ HTTP/1.1 429
+Date: Tue, 20 Aug 2013 14:50:41 GMT
+Status: 429
+X-RateLimit-Limit: 60
+X-RateLimit-Remaining: 0
+X-RateLimit-Reset: 1377013266
+{
+ "message": "Too many requests",
+ "code": 429
+}
+
+```
+
+The following will have unnecessary line-breaks and indentations.
+```html
+
+
+ HTTP/1.1 429
+ Date: Tue, 20 Aug 2013 14:50:41 GMT
+ Status: 429
+ X-RateLimit-Limit: 60
+ X-RateLimit-Remaining: 0
+ X-RateLimit-Reset: 1377013266
+ {
+ "message": "Too many requests",
+ "code": 429
+ }
+
+
+```
+
+> Don't forget to use proper indenting for all code examples. The indenting of the code examples should be independent from the indentation of the surrounding HTML tags.
+
+For referencing code inline, especially when the code is a non-executable snippet, use spans with `class=tag`. For example, use the method listDocuments().
+
+#### Escaping >, <, and &
+Some characters are reserved in HTML and PTHML files, such as `>`, `<`, and `&`. These can be expressed using the following:
+
+- `&` becomes `&`
+- `<` becomes `<`
+- `>` becomes `>`
+
+#### Placeholder Values
+- Be consistent with placeholder values for name type fields across languages. For example, all examples for the Databases query guide should use the database `catalogue` and collection `movies`.
+- Where applicable, use `"unique()"` for ids that can be auto-generated.
+- Use a concise value like `"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ..."` for hash values like long IDs and API keys.
+- Use a placeholder for hostnames like `"https://[HOSTNAME_OR_IP]/v1"` in code examples, but be consistent.
+- Use a known generic name as a place holder like `"John Doe"`, avoid real name and celeberty names.
+- Use generic email passwords as placeholders like `"email@example.com", "password"`.
+- Use a relative file name that is context appropriate like `"img/file.png"`.
+- Where possible, use names for teams, collections, databases, buckets, and other resources that are contextually appropriate and hint at the resource type. This is especially true for code examples in guides like `const result = storage.getFilePreview('image_bucket', 'smiling_penguin.png', '240px', '180px');`, where the parameters passed in are not described.
+- Use sensible variable names :)
+
### Notices
+Use notices to point out important information, especially those relevant for first time readers.
+
+Use the following HTML structure to add important notes inside your docs:
+
+```html
+
+ Important Message
+ Message content here.
+
+```
### Screenshots
+Use the following HTML structure to add images. You can also add support for dark and light mode versions. If no dark mode is provided, light mode will be the fallback. Don't forget to provide alternative text for user accessibility and a description for each image.
+
+```php
+setParam('srcLight', '/images-ee/docs/functions-light.png')
+ ->setParam('srcDark', '/images-ee/docs/functions-dark.png')
+ ->setParam('alt', 'Function settings page.')
+ ->setParam('description', 'Function settings page.')
+ ->render();
+?>
+```
+
+All screenshots should be in PNG format and taken from a 1290 x 848 px viewport. Appwrite dashboard screenshots should display the account name `Walter O'Brian` with a profile image of WO. Do not include any sensitive data in images. Do not include any sensitive data in images.
### Terminology
Appwrite has many services and features. Our word choices must be consistent across the many documentation pages to communicate clearly and precisely.
@@ -24,6 +266,8 @@ Appwrite has many services and features. Our word choices must be consistent acr
| 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. |
+| Client Integration | Refers to Appwrite integrations in Web, Flutter, Android, and Apple applications using session authentication. |
+| Server Integration | Refers to Appwrite integrations on the backend using API authentication. Avoid the phrasing "Admin Mode" and focus on the difference of session vs API based authentication. |
| 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. |
@@ -32,7 +276,6 @@ Appwrite has many services and features. Our word choices must be consistent acr
| 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** |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -46,13 +289,8 @@ Appwrite has many services and features. Our word choices must be consistent acr
| 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
+#### Databases
| **Term** | **Suggested Usage** |
|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -62,8 +300,7 @@ Appwrite has many services and features. Our word choices must be consistent acr
| 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).|
+| Query Methods | These are the different methods provided by Appwrite SDKs to compose queries. For example `Query.lessThanEqual("score", 10)` or `Query.orderDesc("attribute")` are query methods.|
#### Storage
@@ -84,4 +321,25 @@ Appwrite has many services and features. Our word choices must be consistent acr
| 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 settings of a function. These are referred to as "variables" rather than "environment variables".|
-### Spell Checking
+
+#### Permissions
+| **Term** | **Suggested Usage** |
+|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Appwrite Resource | An Appwrite resource can be a database, collection, document, bucket, or file. Each resource has its own set of permissions to define who can interact with it. |
+| Permissions | Use "Permissions" to describe granted access to a resource in session based authentication. This encapsulates permission level, role, and type. For example: `Permission.update(Role.team("writers"))`. |
+| 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).|
+| Permission Types | Use "permission types" to describes how a resource can be accessed(read, create, update, delete, etc).|
+| Permission Roles | Use "role" to describe to describe who can access a resource (anyone, a registered user, a team, etc).|
+| 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.|
+| Scope | Use "Scope" to describe which resources can be accessed. This is mainly used to describe concepts in API authentication. |
+| API Key | Used for authentication in Server Integrations. API keys ignore permission roles and types defined, but are restricted by scope when the keys are created. |
+
+
+### Grammar and Spell Checking
+Run edited pieces of writing through a spell and grammar checking service like Grammarly before contributing changes. Appwrite's documentation follows the [Associated Press (AP) Stylebook](https://www.apstylebook.com/) for grammar and punctuation related guidelines. Appwrite follows American spelling, refer to [Mariam-Webster](https://www.merriam-webster.com/) when unsure of the correct spelling.
+
+We suggest the following free software resources to assist your writing process:
+- [The Hemingway App](https://hemingwayapp.com/)
+- [Grammarly](https://www.grammarly.com/)
+- [AP style of headline capitalization](https://capitalizemytitle.com/style/AP/)