propose baseline for style guidelines

README.md

@@ -1,16 +1,204 @@
 # 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
+<h2><a href="/docs/command-line#installation" id="installation">Installation</a></h2>
+```
+
+### 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 `<a href="/docs">Documentation</a>`. When referencing a specific section of a page, link to the section heading where possible. For example `<a href="/docs/databases#databases">Create Your Databases</a>`.
+
+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
+<p>
+<a href="/docs/environment-variables"><i class="icon-angle-circled-right"></i>Learn more about environment variables</a>
+</p>
+```
+
+### 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, `<span class="tag">appwrite.json</span>` or `<span class="tag">https://[HOSTNAME_OR_IP]/v1</span>`.
+
+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
+<ol>
+    <li>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.</li>
+    <li>Create a script to backups and restore your InfluxDB stats. If you don’t care much about your server stats, you can skip this.</li>
+    <li>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.</li>
+</ol>
+```
 
 ### Code Examples
 
+Use the following HTML structure to present code examples:
+
+```html
+<div class="ide margin-top-small" data-lang="ruby" data-lang-label="Ruby SDK">
+    <pre class="line-numbers"><code class="prism language-ruby" data-prism>#ruby code here...</code></pre>
+</div>
+```
+
+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
+
+For showing examples in multiple languages use the list structure:
+
+```html
+<ul class="phases clear" data-ui-phases>
+    <li>
+        <h3>Node.js</h3>
+        <div class="ide margin-top-small" data-lang="nodejs" data-lang-label="Node.js SDK">
+            <pre class="line-numbers"><code class="prism language-javascript" data-prism>// node code here...</code></pre>
+        </div>
+    </li>
+    <li>
+        <h3>PHP</h3>
+
+        <div class="ide margin-top-small" data-lang="php" data-lang-label="PHP SDK">
+            <pre class="line-numbers"><code class="prism language-php" data-prism>//php code here..</code></pre>
+        </div>
+    </li>
+</ul>
+```
+
+For multi-line code examples, the code must be pasted in verbatim between the `<code>` tags.
+
+The following will render correctly:
+```html
+<div class="ide">
+    <pre class="line-numbers"><code class="prism language-http" data-prism>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
+}</code></pre>
+</div>
+```
+
+The following will have unnecessary line-breaks and indentations. 
+```html
+<div class="ide">
+    <pre class="line-numbers"><code class="prism language-http" data-prism>
+        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
+        }
+    </code></pre>
+</div>
+```
+
+> 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 <span class="tag">listDocuments()</span>.
+
+
+
+#### 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 protected]", "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. 
+
+Use the following HTML structure to add important notes inside your docs:
+
+```html
+<div class="notice">
+  <h2>Important Message</h2>
+  <p>Message content here.</p>
+</div>
+```
 
 ### 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
+<?php
+$image = new View(__DIR__.'/../general/image.phtml');
+    echo $image
+        ->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 +220,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 +237,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 +269,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/)