This repository was archived by the owner on Sep 29, 2023. It is now read-only.
Updates Contributing Guidelines for Documentation and Content #195
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
adityaoberai
reviewed
Jun 6, 2022
Co-authored-by: Aditya Oberai <31401437+adityaoberai@users.noreply.github.com>
Co-authored-by: Aditya Oberai <31401437+adityaoberai@users.noreply.github.com>
Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>
Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>
Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>
Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>
Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>
Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>
Co-authored-by: Steven <1477010+stnguyen90@users.noreply.github.com>
This reverts commit a9e267c.
Suggest a standard set of terms to reduce confusion across docs
eldadfux
reviewed
Jul 30, 2022
| |-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | 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. | |
There was a problem hiding this comment.
Should we include terms related to big files support such as chunks and stream download?
| |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | 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" on the dashboard or using `functions.create()` method. No code is uploaded. | |
There was a problem hiding this comment.
Why do we specifically mention create here but not in other sections?
| | 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 settings of a function. These are referred to as "variables" rather than "environment variables".| |
There was a problem hiding this comment.
Might be relevant to include build.
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What is this PR?
This PR aims to define and extend guidelines for creating documentation and content for Appwrite.
Why do we need this PR?
This will serve as a reference for self and peer review for new pieces of documentation and content for sake of consistency.
Proposed outline
The new proposed document will have the following sections.
Documentation Guidelines
This section will contain documentation specific
🚀 Contributing
Describes the workflow to contribute new documentation
Before Proposing Additions
Describes how to decide where to make these additions
Style Guidelines
Describes formatting and style guidelines, including the following subsections
Code Examples
How to include code examples
Notices
When to include notices in documentation
Screenshots
How to format screenshots for documentation
Terminology
Define standard format and spelling for various Appwrite services and commonly confused terminology.
Spell Checking
Define which form of English spelling we adhere to, and the optional use of Grammarly.
Content Guidelines
This section will contain content specific guidelines, for blogs, images, and videos to be posted on official Appwrite accounts.
Voice and Tone
Discusses appropriate choice of voice and tone when writing technical blogs.
Style Guidelines
Describes formatting and style guidelines, including the following subsections
Code Examples
How to include code examples for blog content and video/image content
Screenshots
How to format screenshots for documentation
Commonly used tools
Commonly used tools to create screenshots and code examples, where to find branding assets.
Terminology
Define standard format and spelling for various Appwrite services and commonly confused terminology.
Spell Checking
Define which form of English spelling we adhere to and use of Grammarly.
Process Guidelines
Describes the process of creating outlines, requesting design assets, and the review process of new content.