propose baseline for style guidelines #229

gewenyu99 · 2022-07-27T21:05:26Z

Style Guideline Proposal

What is this PR?

This PR proposes a set of refined styling guidelines to make our documentation more consistent and easier to read. This is intended as a styling suggestion for all documentation contributors to reference and for all reviewers to reference.

New UI Elements Needed

We need a monospace UI element to reference code, file names, hostnames, and other types of text that look better as monospace. Similar to the backtick ` in GitHub, so we can reference monospace inline, like appwrite.json.

Why is this important?

As the community and project grow in complexity, we need to make sure the information, voice, and formatting in our documentation remain consistent.

Notice the way the <application> tag and [PROJECT_ID].

Notice how the "X-Appwrite-Webhook-Signature" is display extremely differently.

First with a span tag

Then with bold text.

Notice the below example of how we reference UI elements, first with quoted plain text:

Then with quoted bold:

This makes the documentation look less professional and difficult to read without consistent visual hints

Notice how these examples from the same guide have a different placeholder for the project. This makes it much harder to follow when I switch from one language to another:

Meldiron

Amazing stuff 😇 Left a few comments

Meldiron · 2022-08-01T05:47:05Z

README.md

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


We could also mention that endpoint names or descriptions are to be updated in appwrite/appwrite.

Meldiron · 2022-08-01T05:47:53Z

README.md

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


Is it clear what should go into "Guides", what into "Advanced" and what should not be part of docs? (like OAuth article)

This is something worth discussing. I heard Steven and Torsten are having a conversation about how to divide the guides up, but the idea is guides are "getting started" for the primary services, everything else that's not core/self-host related will be "Advanced".

Meldiron · 2022-08-01T05:49:56Z

README.md

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


I get what you mean, but I don't think these links are called relative. Relative would be ../docs/command-line. Maybe there is a batter word for internal VS external links?

https://www.w3.org/TR/WD-html40-970917/htmlweb.html

I believe this is in fact relative:

README.md

Meldiron · 2022-08-01T05:53:51Z

README.md

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


Let's please also mention how to put <> symbols in there. It's relevant in some languages and breaks if you don't do it properly. I think we used it in Flutter.

Yus. I agrees

Meldiron · 2022-08-01T05:56:59Z

README.md

+  <h2>Important Message</h2>
+  <p>Message content here.</p>
+</div>
+```

 ### Screenshots


Reading this section, we say:

If no dark mode is provided, light mode will be the fallback

All screenshots of the Appwrite dashboard should support light and dark mode

All screenshot of the Appwrite dashboard should support light and dark mode.

We say it too much. Just making sure we are aware and do it in purpose.

README.md

stnguyen90 · 2022-08-01T21:02:28Z

README.md

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


Should the Guides and Rest API bullet point orders be swapped to match the order in our docs?

We're gonna swap the order in docs soon ;)

README.md

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

gewenyu99 · 2022-10-09T23:27:59Z

I think we might need to go back to "Appwrite Console'

It already exists in way to many places for us to change, and it never really caused confusion. This was a bad call on my part.

Update Install guide to conform to guidelines proposed in PR #229.

Vincent (Wen Yu) Ge added 3 commits July 27, 2022 21:03

propose baseline for style guidelines

2da8b09

code placehold guidelines

76c5e1a

complete code and link examples

d6cb5a5

gewenyu99 marked this pull request as ready for review July 28, 2022 21:39

stnguyen90 self-requested a review July 29, 2022 22:57

Meldiron reviewed Aug 1, 2022

View reviewed changes

stnguyen90 suggested changes Aug 1, 2022

View reviewed changes

gewenyu99 and others added 7 commits August 2, 2022 16:23

Penguin!

3219c43

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

Update README.md

6754d0b

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

Grammar check by Steven

957e00c

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

Implement Matej's suggestions

b91d0c6

add prism aliases

445878f

remove redudant description about darkmode

80948be

update with latest changes in 1.0 and <code> tags

d6770e7

gewenyu99 pushed a commit that referenced this pull request Oct 4, 2022

Update Database guide to conform to guidelines proposed in PR #229.

931611b

gewenyu99 mentioned this pull request Oct 4, 2022

Databases Relationships Refactor Proposal #274

Closed

gewenyu99 pushed a commit that referenced this pull request Oct 4, 2022

Update Install guide to conform to guidelines proposed in PR #229.

1a21adc

gewenyu99 mentioned this pull request Oct 4, 2022

Update Install guide to conform to guidelines proposed in PR #229. #275

Merged

Update README.md

5f73005

gewenyu99 pushed a commit that referenced this pull request Oct 5, 2022

Update production guide to conform to guidelines proposed in PR #229

f813f4e

gewenyu99 mentioned this pull request Oct 17, 2022

Remove references to admin mode appwrite/appwrite#4520

Merged

christyjacob4 added a commit that referenced this pull request Nov 14, 2022

Merge pull request #275 from appwrite/install-style-update

a3ccf6d

Update Install guide to conform to guidelines proposed in PR #229.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

propose baseline for style guidelines #229

propose baseline for style guidelines #229

gewenyu99 commented Jul 27, 2022 •

edited

Loading

Meldiron left a comment

Meldiron Aug 1, 2022

Meldiron Aug 1, 2022

gewenyu99 Aug 2, 2022

Meldiron Aug 1, 2022

gewenyu99 Aug 2, 2022

Meldiron Aug 1, 2022

gewenyu99 Aug 2, 2022

Meldiron Aug 1, 2022

gewenyu99 Aug 2, 2022

stnguyen90 Aug 1, 2022

gewenyu99 Aug 3, 2022

gewenyu99 commented Oct 9, 2022

propose baseline for style guidelines #229

Are you sure you want to change the base?

propose baseline for style guidelines #229

Conversation

gewenyu99 commented Jul 27, 2022 • edited Loading

Style Guideline Proposal

What is this PR?

New UI Elements Needed

Why is this important?

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

gewenyu99 commented Oct 9, 2022

gewenyu99 commented Jul 27, 2022 •

edited

Loading