From 2da8b0993286e527fb2cbd12f13403b8769679aa Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Wed, 27 Jul 2022 21:03:41 +0000 Subject: [PATCH 01/11] propose baseline for style guidelines --- README.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 125 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 761e7c6ff..2540994b6 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,133 @@ # Documentation Guidelines +The official https://appwrite.io/docs documentation source code. ## 🚀 Contributing +1. Clone the repository +2. Update, add, or fix current docs +3. Once content is ready, raise a PR ## Before Proposing Additions +Documentation is an integral part of Appwrite and follows the same philosophy of quick to get started, easy to grow. Before proposing additions to Appwrite's documentation, think about where these additions fit best. +- The **Getting Started** section helps a developer create their first Appwrite project and make their first requests so they can begin exploring Appwrite. Avoid adding unnecessary information to this section so a developer's first-impressions remains quick and smooth. +- The **Guides** section helps a developer get comfortable with individual Appwrite services. Guides are structured to walk a developer through features of an Appwrite service. The topics should be ordered by level of complexity, where complex topics are positioned later into a guide. +- The **REST API** section helps a developer understand details of individual endpoints. Additions to REST API documentation should remain focused on the API endpoint itself. Avoid adding information about related endpoints and services that are not integral to undestanding documented endpoint. Code example changes should be submitted to the [SDK Generator repo](https://github.com/appwrite/sdk-generator). +- The **Advanced** section helps a developer learn more complicated concepts like pagination or using permissions. If your proposed addition are not a core component of using a service or requires lengthy explanation, consider adding them to **Advanced**. +- **External Content** like blog posts and videos are used for documenting examples or integrating Appwrite with third party services. If your proposed addition involves content that are not focused on specific ways of using Appwrite, create a piece of external content. Add the content to the [Awesome Appwrite](https://github.com/appwrite/awesome-appwrite) catalog. The Appwrite team will also be glad to share the external content on Discord and on Appwrite's social accounts. + +As a general note, if a behavior is excessively difficult to explain or feels awkwardly complex to document, there is a chance that it is also a design/product issue or bug. Consult Appwrite maintainers and open an issue. ## Style Guidelines +When contributing to Appwrite's documentation, use these guidelines to format your contributions. +### Page Hierarchy +Titles and subtitles should follow a logical hierarchy (h1-h6) using the [AP style of headline capitalization](https://capitalizemytitle.com/style/AP/). Page headings and subheadings should be hyperlinked for ease of reference and have an appropriate ID. For examples: +```html +

Installation

+``` + +### Naming Files +File names should reflect it's content. In general, use dash separated file names that reference the title of the page. For example "Documentation Guidelines" could be "documentation-guidelines". +### Internal and External Links +Internal links that direct to any link under [https://appwrite.io](/docs/command-line#installation) should be relative and precise. For example, when referencing the Appwrite Documentation page, use the `Documentation`. When referencing a specific section of a page, link to the section heading where possible. For example `Create Your Databases`. + +External links (not https://appwrite.io) should be opened in a new tab (`target="_blank"`) and have an HTML attribute of `rel="noopener"`. +### 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". + +### Referencing File Paths, URLs, and IDs +When referencing file paths, URLs, IDs, or any text appropriate for monospace representation, use a span element with `class=tag` inline. For example, `appwrite.json` or `https://[HOSTNAME_OR_IP]/v1`. ### Code Examples +Use the following HTML structure to present code examples: + +```html +
+ 
#ruby code here...
+
+``` + +Code examples should require minimum modifications to be executed where possible. + +As of writing this, these are the supported languages for code examples: + +* Markup +* CSS +* CLike +* JavaScript +* Bash +* C# +* Dart +* Go +* GraphQL +* HTTP +* Java +* JSON +* Kotlin +* Markup-templating +* PHP +* Powershell +* Python +* Ruby +* Swift +* TypeScript +* YAML + +For showing examples in multiple languages use the list structure: + +```html + +``` + +> 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(). + ### 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 console screenshots should display the account name `Walter O'Brian` with a profile image of WO. Do not include any sensitive data in images. All screenshots of the Appwrite dashboard should support light and dark mode. + +Do not include any sensitive data in images. All screenshot of the Appwrite dashboard should support light and dark mode. ### Terminology Appwrite has many services and features. Our word choices must be consistent across the many documentation pages to communicate clearly and precisely. @@ -32,7 +149,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** | |------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -50,8 +166,6 @@ Appwrite has many services and features. Our word choices must be consistent acr | 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** | @@ -84,4 +198,11 @@ 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 + +### 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/) From 76c5e1ad3ea339e712febed907f71d319868a764 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Wed, 27 Jul 2022 21:55:25 +0000 Subject: [PATCH 02/11] code placehold guidelines --- README.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2540994b6..7607c8f78 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,8 @@ When referencing example copy text that appears or could appear on a piece of UI ### Referencing File Paths, URLs, and IDs When referencing file paths, URLs, IDs, or any text appropriate for monospace representation, use a span element with `class=tag` inline. For example, `appwrite.json` or `https://[HOSTNAME_OR_IP]/v1`. +When using generic strings, use double quotes `"`. Double quotes express a string in **all** languages, but single quotes `'` in some languages like Java and C++ represent a **char**. This makes them difficult to copy and paste. + ### Code Examples Use the following HTML structure to present code examples: @@ -48,7 +50,7 @@ Use the following HTML structure to present code examples: ``` -Code examples should require minimum modifications to be executed where possible. +Code examples should require minimum modifications to be executed where possible (working and self-contained). As of writing this, these are the supported languages for code examples: @@ -98,6 +100,17 @@ For showing examples in multiple languages use the list structure: For referencing code inline, especially when the code is a non-executable snippet, use spans with `class=tag`. For example, use the method listDocuments(). +#### 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_penguine.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. From d6cb5a55a8a01126cf12fea601fd31e0ad4542aa Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Thu, 28 Jul 2022 19:00:15 +0000 Subject: [PATCH 03/11] complete code and link examples --- README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/README.md b/README.md index 7607c8f78..bf75d50c2 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,15 @@ File names should reflect it's content. In general, use dash separated file name Internal links that direct to any link under [https://appwrite.io](/docs/command-line#installation) should be relative and precise. For example, when referencing the Appwrite Documentation page, use the `Documentation`. When referencing a specific section of a page, link to the section heading where possible. For example `Create Your Databases`. External links (not https://appwrite.io) should be opened in a new tab (`target="_blank"`) and have an HTML attribute of `rel="noopener"`. + +Links that are not inline: + +```html +

+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**. @@ -40,6 +49,17 @@ When referencing file paths, URLs, IDs, or any text appropriate for monospace re When using generic strings, use double quotes `"`. Double quotes express a string in **all** languages, but single quotes `'` in some languages like Java and C++ represent a **char**. This makes them difficult to copy and paste. +### Procedural Instructions +When describing steps to do something, especially UI workflows, use an ordered list. For example: + +```html +
    +
  1. Create a script to backups and restore your MariaDB Appwrite schema. Note that trying to backup MariaDB using a docker volume backup can result in a corrupted copy of your data. It is recommended to use MariaDB or MySQL built-in tools for this.
    2. +
  2. Create a script to backups and restore your InfluxDB stats. If you don’t care much about your server stats, you can skip this.
    3. +
  3. Create a script to backup Appwrite storage volume. There are many online resources explaining different ways to backup a docker volume. When running on multiple servers, it is very recommended to use an attachable storage point. Some cloud providers offer integrated backups to such attachable mount like GCP, AWS, DigitalOcean, and the list continues.
    4. +
+``` + ### Code Examples Use the following HTML structure to present code examples: @@ -96,10 +116,48 @@ For showing examples in multiple languages use the list structure: ``` +For multi-line code examples, the code must be pasted in verbatim between the `` 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(). + + #### 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. From 3219c439c4df80273143c23700ee74df7f1fac0b Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 2 Aug 2022 16:23:06 -0400 Subject: [PATCH 04/11] Penguin! 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 bf75d50c2..eaa0ac88d 100644 --- a/README.md +++ b/README.md @@ -166,7 +166,7 @@ For referencing code inline, especially when the code is a non-executable snippe - 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_penguine.png', '240px', '180px');`, where the parameters passed in are not described. +- 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 From 6754d0bb31fe6100e0065b93eb6c61efc171f3c7 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 2 Aug 2022 16:23:43 -0400 Subject: [PATCH 05/11] 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 eaa0ac88d..fe0ab673d 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Documentation is an integral part of Appwrite and follows the same philosophy of - The **Advanced** section helps a developer learn more complicated concepts like pagination or using permissions. If your proposed addition are not a core component of using a service or requires lengthy explanation, consider adding them to **Advanced**. - **External Content** like blog posts and videos are used for documenting examples or integrating Appwrite with third party services. If your proposed addition involves content that are not focused on specific ways of using Appwrite, create a piece of external content. Add the content to the [Awesome Appwrite](https://github.com/appwrite/awesome-appwrite) catalog. The Appwrite team will also be glad to share the external content on Discord and on Appwrite's social accounts. -As a general note, if a behavior is excessively difficult to explain or feels awkwardly complex to document, there is a chance that it is also a design/product issue or bug. Consult Appwrite maintainers and open an issue. +As a general note, if a behavior is excessively difficult to explain or feels awkwardly complex to document, there is a chance that it is also a design/product issue or bug. If that's the case, consult Appwrite maintainers and [open an issue](https://github.com/appwrite/appwrite/issues/new/choose). ## Style Guidelines When contributing to Appwrite's documentation, use these guidelines to format your contributions. From 957e00c9b99a64c085e75150c712eef3f7764124 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 2 Aug 2022 16:24:28 -0400 Subject: [PATCH 06/11] Grammar check by Steven 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 fe0ab673d..e825a5271 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Documentation is an integral part of Appwrite and follows the same philosophy of - The **Guides** section helps a developer get comfortable with individual Appwrite services. Guides are structured to walk a developer through features of an Appwrite service. The topics should be ordered by level of complexity, where complex topics are positioned later into a guide. - The **REST API** section helps a developer understand details of individual endpoints. Additions to REST API documentation should remain focused on the API endpoint itself. Avoid adding information about related endpoints and services that are not integral to undestanding documented endpoint. Code example changes should be submitted to the [SDK Generator repo](https://github.com/appwrite/sdk-generator). - The **Advanced** section helps a developer learn more complicated concepts like pagination or using permissions. If your proposed addition are not a core component of using a service or requires lengthy explanation, consider adding them to **Advanced**. -- **External Content** like blog posts and videos are used for documenting examples or integrating Appwrite with third party services. If your proposed addition involves content that are not focused on specific ways of using Appwrite, create a piece of external content. Add the content to the [Awesome Appwrite](https://github.com/appwrite/awesome-appwrite) catalog. The Appwrite team will also be glad to share the external content on Discord and on Appwrite's social accounts. +- **External Content** like blog posts and videos are used for documenting examples or integrating Appwrite with third party services. If your proposed addition involves content that is not focused on specific ways of using Appwrite, create a piece of external content and add the content to the [Awesome Appwrite](https://github.com/appwrite/awesome-appwrite) catalog. The Appwrite team will also be glad to share the external content on Discord and Appwrite's social accounts. As a general note, if a behavior is excessively difficult to explain or feels awkwardly complex to document, there is a chance that it is also a design/product issue or bug. If that's the case, consult Appwrite maintainers and [open an issue](https://github.com/appwrite/appwrite/issues/new/choose). From b91d0c64a944987f5af6f2d3d02e505e31cbc361 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 2 Aug 2022 21:32:33 +0000 Subject: [PATCH 07/11] Implement Matej's suggestions --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e825a5271..7e98f5eb1 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,8 @@ The official https://appwrite.io/docs documentation source code. ## Before Proposing Additions Documentation is an integral part of Appwrite and follows the same philosophy of quick to get started, easy to grow. Before proposing additions to Appwrite's documentation, think about where these additions fit best. - The **Getting Started** section helps a developer create their first Appwrite project and make their first requests so they can begin exploring Appwrite. Avoid adding unnecessary information to this section so a developer's first-impressions remains quick and smooth. -- The **Guides** section helps a developer get comfortable with individual Appwrite services. Guides are structured to walk a developer through features of an Appwrite service. The topics should be ordered by level of complexity, where complex topics are positioned later into a guide. -- The **REST API** section helps a developer understand details of individual endpoints. Additions to REST API documentation should remain focused on the API endpoint itself. Avoid adding information about related endpoints and services that are not integral to undestanding documented endpoint. Code example changes should be submitted to the [SDK Generator repo](https://github.com/appwrite/sdk-generator). +- The **Guides** section helps a developer get comfortable with individual Appwrite services. Guides are structured to walk a developer through features of an Appwrite service. The topics should be ordered by level of complexity, where complex topics are positioned later into a guide. +- The **REST API** section helps a developer understand details of individual endpoints. Additions to REST API documentation should remain focused on the API endpoint itself. Avoid adding information about related endpoints and services that are not integral to undestanding documented endpoint. Code example changes should be submitted to the [SDK Generator repo](https://github.com/appwrite/sdk-generator) and endpoint descriptions can be found in the [Appwrite repo](https://github.com/appwrite/appwrite). - The **Advanced** section helps a developer learn more complicated concepts like pagination or using permissions. If your proposed addition are not a core component of using a service or requires lengthy explanation, consider adding them to **Advanced**. - **External Content** like blog posts and videos are used for documenting examples or integrating Appwrite with third party services. If your proposed addition involves content that is not focused on specific ways of using Appwrite, create a piece of external content and add the content to the [Awesome Appwrite](https://github.com/appwrite/awesome-appwrite) catalog. The Appwrite team will also be glad to share the external content on Discord and Appwrite's social accounts. From 445878fcfa457a56b6169dcb6d57e0184fe9de22 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Wed, 3 Aug 2022 19:45:06 +0000 Subject: [PATCH 08/11] add prism aliases --- README.md | 54 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 7e98f5eb1..294e366dc 100644 --- a/README.md +++ b/README.md @@ -72,29 +72,37 @@ Use the following HTML structure to present code examples: Code examples should require minimum modifications to be executed where possible (working and self-contained). -As of writing this, these are the supported languages for code examples: - -* Markup -* CSS -* CLike -* JavaScript -* Bash -* C# -* Dart -* Go -* GraphQL -* HTTP -* Java -* JSON -* Kotlin -* Markup-templating -* PHP -* Powershell -* Python -* Ruby -* Swift -* TypeScript -* YAML +The `data-lang` attribute changes the top right label pill's color. The `data-lang-label` attribute changes the top right label pill's text. + +The supported `data-lang` attribute values can be found in the `ide.less` [style file](https://github.com/appwrite/appwrite/blob/1a0f740459fde58dc41112861f47bc06d1ae5c4c/public/styles/ide.less#L30). + +Appwrite uses Prism to highlight code examples. The `class` attribute of the `code` html tag changes how Prism highlights code, The format is `language-`. + +As of writing this, these are the supported languages and their Prism alias for code examples: + +|Language |Prism Alias | +|-------------------|-------------------------------------------------| +| Markup | markup, html, xml, svg, mathml, ssml, atom, rss | +| CSS | css | +| CLike | clike | +| JavaScript | javascript, js | +| Bash | bash, shell | +| C# | csharp, cs, dotnet | +| Dart | dart | +| Go | go | +| GraphQL | graphql | +| HTTP | http | +| Java | java | +| JSON | json | +| Kotlin | kotlin, kt, kts | +| Markup-templating | markup-templating | +| PHP | php | +| Powershell | powershell | +| Python | python, py | +| Ruby | ruby | +| Swift | swift | +| TypeScript | typescript, ts | + For showing examples in multiple languages use the list structure: From 80948be2426ed4488cba27551dd878d07581048c Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Wed, 3 Aug 2022 20:28:42 +0000 Subject: [PATCH 09/11] remove redudant description about darkmode --- README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 294e366dc..6f43edb29 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,12 @@ The following will have unnecessary line-breaks and indentations. 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`. @@ -204,9 +209,7 @@ $image = new View(__DIR__.'/../general/image.phtml'); ?> ``` -All screenshots should be in PNG format and taken from a 1290 x 848 px viewport. Appwrite console screenshots should display the account name `Walter O'Brian` with a profile image of WO. Do not include any sensitive data in images. All screenshots of the Appwrite dashboard should support light and dark mode. - -Do not include any sensitive data in images. All screenshot of the Appwrite dashboard should support light and dark mode. +All screenshots should be in PNG format and taken from a 1290 x 848 px viewport. Appwrite console 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. From d6770e772f8c7ba08569b5c3c7d4eeff2047e986 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Tue, 4 Oct 2022 16:11:33 +0000 Subject: [PATCH 10/11] update with latest changes in 1.0 and tags --- README.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 64 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 6f43edb29..36660faf9 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,7 @@ Titles and subtitles should follow a logical hierarchy (h1-h6) using the [AP sty ### Naming Files File names should reflect it's content. In general, use dash separated file names that reference the title of the page. For example "Documentation Guidelines" could be "documentation-guidelines". + ### Internal and External Links Internal links that direct to any link under [https://appwrite.io](/docs/command-line#installation) should be relative and precise. For example, when referencing the Appwrite Documentation page, use the `Documentation`. When referencing a specific section of a page, link to the section heading where possible. For example `Create Your Databases`. @@ -44,8 +45,8 @@ When referencing buttons, tabs, and other interactive UI elements, use the full 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". -### Referencing File Paths, URLs, and IDs -When referencing file paths, URLs, IDs, or any text appropriate for monospace representation, use a span element with `class=tag` inline. For example, `appwrite.json` or `https://[HOSTNAME_OR_IP]/v1`. +### Verbatim References Inline +Monospace font inline through the use of `` should be used as a visual hint when something is referenced verbatim (literal quote). Anything that can be copied or searched for in code in the exact form presented should be monospace. Common examples are file names, urls, numbers, ids, code, and emails. When using generic strings, use double quotes `"`. Double quotes express a string in **all** languages, but single quotes `'` in some languages like Java and C++ represent a **char**. This makes them difficult to copy and paste. @@ -53,13 +54,55 @@ When using generic strings, use double quotes `"`. Double quotes express a strin When describing steps to do something, especially UI workflows, use an ordered list. For example: ```html -
    +
    1. Create a script to backups and restore your MariaDB Appwrite schema. Note that trying to backup MariaDB using a docker volume backup can result in a corrupted copy of your data. It is recommended to use MariaDB or MySQL built-in tools for this.
    2. Create a script to backups and restore your InfluxDB stats. If you don’t care much about your server stats, you can skip this.
    3. Create a script to backup Appwrite storage volume. There are many online resources explaining different ways to backup a docker volume. When running on multiple servers, it is very recommended to use an attachable storage point. Some cloud providers offer integrated backups to such attachable mount like GCP, AWS, DigitalOcean, and the list continues.
    ``` +### Tables +Consider using a table instead of a list when listing SDK methods, integrations, SDKs, etc. Tables have a stronger visual representation and are easier to read than an unordered list. + +Here's an example of a table: +``` html + + + + + + + + + + + + + + + + + + + + +
    Provider
    + + + + DigitalOcean + + Click to Install +
    + + + + Gitpod + + Click to Install +
    +``` + ### Code Examples Use the following HTML structure to present code examples: @@ -223,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. | @@ -244,11 +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** | |-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -258,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 @@ -281,6 +322,20 @@ Appwrite has many services and features. Our word choices must be consistent acr | 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".| +#### 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. From 5f73005f60eb66b9b0c69e61368ad196f3b2c9c5 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Wed, 5 Oct 2022 15:35:57 -0400 Subject: [PATCH 11/11] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 36660faf9..06365b5b3 100644 --- a/README.md +++ b/README.md @@ -252,7 +252,7 @@ $image = new View(__DIR__.'/../general/image.phtml'); ?> ``` -All screenshots should be in PNG format and taken from a 1290 x 848 px viewport. Appwrite console 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. +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.