From 941d32dcdbbffc189c23af2643dd3eb421049fcc Mon Sep 17 00:00:00 2001 From: Charis <26616127+charislam@users.noreply.github.com> Date: Thu, 23 Nov 2023 15:01:12 -0500 Subject: [PATCH] docs: add contributing guide for docs (#19146) Co-authored-by: Copple <10214025+kiwicopple@users.noreply.github.com> --- .prettierignore | 1 + apps/docs/CONTRIBUTING.md | 323 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 324 insertions(+) create mode 100644 apps/docs/CONTRIBUTING.md diff --git a/.prettierignore b/.prettierignore index a11b83a7238..2d39a3f6189 100644 --- a/.prettierignore +++ b/.prettierignore @@ -14,3 +14,4 @@ apps/docs/pages/guides/auth/*.mdx apps/docs/pages/guides/integrations/*.mdx apps/studio/public apps/**/.turbo +apps/docs/CONTRIBUTING.md diff --git a/apps/docs/CONTRIBUTING.md b/apps/docs/CONTRIBUTING.md new file mode 100644 index 00000000000..81875b59025 --- /dev/null +++ b/apps/docs/CONTRIBUTING.md @@ -0,0 +1,323 @@ +# Contributing to Supabase docs + +Our docs help developers to get started and keep succeeding with Supabase. We welcome contributions from everyone. + +If you'd like to contribute, see our list of [recommended issues](https://github.com/supabase/supabase/issues?q=is%3Aopen+is%3Aissue+label%3Adocumentation+label%3A%22help+wanted%22). We also welcome you to open a PR or a new issue with your question. + +Here are some general guidelines on writing docs for Supabase. + +## General principles + +Docs should be helpful, quick to read, and easy to understand. We have an audience of global readers who speak different native languages. + +To make docs as clear as possible: + +- Write for the user. Think about what task they want to complete by reading your doc. Tell them what, and only what, they need to know. +- Write like you talk. Use words and sentences that sound natural when speaking. Cut unnecessary words. Read your writing out loud to help you choose the clearest and simplest phrases. +- Each paragraph should have one topic only. Start a new paragraph whenever you change the topic. Don't worry about paragraphs being too short. +- Avoid using idioms and colloquialisms, such as `piece of cake`. These phrases are often specific to a region or culture. +- Refer to the reader as `you`. Don't use `we` to refer to the reader. Use `we` only to refer to the Supabase team. + +## Document types + +Supabase docs contain 4 types of documents. Before you start writing, think about what type of doc you need. + +### Explainers + +Explainers help the reader to learn a topic. They are conceptual and mostly prose-based. They can include: + +- A description of _what_ a feature is +- Some reasons _why_ it is useful +- Some examples of _when_ to use it +- A high-level explanation of _how_ it works + +They shouldn't include: + +- Instructions on how to use it + +### Tutorials + +Tutorials are goal-oriented. They help a reader to finish a large, complex goal, such as setting up a web app that uses multiple Supabase features. + +Tutorials mix prose explanations with procedures (lists of steps for the reader to follow). They provide context for why certain instructions are given. + +For inspiration, see [an example of a tutorial](https://supabase.com/docs/guides/getting-started/tutorials/with-nextjs). + +### Guides + +Guides are also goal-oriented, but they focus on shorter, more targeted tasks. For example, a guide might explain how to set up user login for an app. + +Guides contain mostly procedures. Think of an instruction manual for building a desk: it's a list of concise steps that the user can go through quickly. + +For inspiration, see [an example of a guide](https://supabase.com/docs/guides/auth/auth-email). + +### Reference + +References are factual and to the point. Think of dictionary entries. + +They should include: + +- Function parameters +- Return types +- Code samples +- Warnings for critical errors (for example, missteps that can cause data loss) + +They shouldn't include: + +- Explanations of the context for a feature +- Examples of use cases +- Multi-step instructions + +## Repo organization + +Most docs pages are contained in the `apps/docs/pages` directory. Some docs sections are federated from other repositories, for example [`pg_graphql`](https://github.com/supabase/pg_graphql/tree/master/docs). Reference docs are generated from spec files in the `spec` directory. + +You can usually identify a federated or reference doc because it uses a Next.js dynamic route (for example, `[[...slug]].tsx`). Look for the spec file import or the repo definition to find the content location. + +Example spec file import: + +```js +import specFile from '~/../../spec/transforms/analytics_v0_openapi_deparsed.json' assert { type: 'json' } +``` + +Example repo definition: + +```js +const org = 'supabase' +const repo = 'pg_graphql' +const branch = 'master' +const docsDir = 'docs' +const externalSite = 'https://supabase.github.io/pg_graphql' +``` + +## File structure + +The Supabase docs use [MDX](https://mdxjs.com/). + +Adding a new doc requires: + +- A layout +- Metadata +- A page export +- A navigation entry (in a separate file) + +```js +// required import +import Layout from '~/layouts/DefaultGuideLayout' + + +/* + * required metadata fields + * title: required - page title + * description: required - page description + * + * optional metadata fields + * id: optional - not currently being used + * subtitle: optional - displayed below the title + * sidebar_label: optional - if you want the sidebar text to be different from the title + * hide_table_of_contents: optional - hides the table of contents on the right side + * tocVideo: optional - a YouTube slug, displays the video above the table of contents + */ +export const meta = { + id: 'nextjs-server-components', + title: 'Supabase Auth with Next.js Server Components', + description: + 'Authentication helpers for creating an authenticated Supabase client in Next.js 13 app directory Server Components.', + sidebar_label: 'Next.js Server Components', +} + +// content +You can use **Markdown syntax**. + +// required export +export const Page = ({ children }) => + +export default Page +``` + +The navigation is defined in [`NavigationMenu.constants.ts`](https://github.com/supabase/supabase/blob/master/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts). + +Add an entry with the `name`, `url`, and (optional) `icon` for your page. + +## Content reuse + +If you copy the same content multiple times across different files, create a **partial** for content reuse instead. Partials are MDX files contained in [`apps/docs/components/MDX`](https://github.com/supabase/supabase/tree/master/apps/docs/components/MDX). They contain reusable snippets that can be inserted in multiple pages. For example, you can create a partial to define a common setup step for a group of tutorials. + +To use a partial, import it into your MDX file. You can also set up a partial to automatically import by including it in the `components` within [`apps/docs/components/index.tsx`](https://github.com/supabase/supabase/blob/master/apps/docs/components/index.tsx). + +## Components and elements + +Docs include normal Markdown elements such as lists, and custom components such as admonitions (callouts). + +Here are some guidelines for using elements: + +### Admonitions + +Admonitions (or callouts) draw reader attention to an important point or an aside. They highlight important information, but get less effective if they're overused. + +Use admonitions sparingly. Don't stack them on top of each other. + +Choose the appropriate `type` for your admonition: + +- `danger` to warn the user about any missteps that could cause data loss or data leaks +- `deprecation` to notify the user about features that are (or will soon be) deprecated +- `caution` to warn about anything that could cause a bug or serious user inconvenience +- `tip` to point out helpful but optional actions +- `note` for anything else + +``` + + +Your content here + + +``` + +### Blockquotes + +Don't use blockquotes. + +### Code blocks + +Keep code lines short to avoid scrolling. For example, you can split long shell commands with `\`. + +- **JavaScript/TypeScript** + + The `supabase` repo uses Prettier, which also formats JS/TS in code blocks. Your PR is blocked from merging if the Prettier check fails. Ensure that your code blocks are formatted by running `npm run format`, or by setting up auto-formatting in your IDE. + +- **SQL** + + Prefer lowercase for SQL. For example, `select * from table` rather than `SELECT * FROM table`. + +Optionally specify a filename for the codeblock by including it after the opening backticks and language specifier: + +```md +```ts environment.ts +``` + +Optionally highlight lines by using `mark=${lineNumber}`. + +```md +```js mark=12:13 +``` + +### Footnotes + +Don't use footnotes. + +### Images + +Images are uploaded in the `apps/docs/public/img` folder. + +For vector illustrations, use `svg`. For screenshots and non-vector graphics, use `png`. (These are automatically converted to `webp` for supported browsers.) + +Redact any sensitive information, such as API keys. + +### Links + +Link text should be descriptive. The reader should understand where the link goes from reading the link text alone. This is important for accessibility. For example, don't use `here` as link text. + +But link text shouldn't be too long. Use the shortest part of the link that is descriptive enough. For example, `see the [reference section](/link)` rather than `[see the reference section](/link)`. + +Use relative links when linking within the `supabase.com` domain. For example, `[link to another page in Supabase docs](/docs/guides/getting-started)`. + +### Lists + +Use ordered lists for steps that must be taken one after the other. Use unordered lists when order doesn't matter. + +Use Arabic numerals (`1`, `2`, `3`) for ordered lists and dashes (`-`) for unordered lists. + +Don't nest lists more than two deep. + +```md +1. List item +2. List item + 1. List item + 2. List item +3. List item + - List item + - List item + + - Overly nested list item +``` + +### Tabs + +Use tabs to provide alternative instructions for different platforms or languages. + +The `queryGroup` param is optional. It lets you link directly to a tab by using the query group as a query param in the URL, for example: `https://supabase.com/docs/my-page?packagemanager=ts` + +``` + + + +// ... + + + + +// ... + + + +``` + +### Videos + +Include videos as TOC (Table of Contents) videos rather than putting them in the main text. + +You can define a TOC video in the page metadata: + +```js +export const meta = { + ... + tocVideo: 'rzglqRdZUQE', +} +``` + +## Styling, formatting, and grammar + +Don't worry too much about grammar rules. Grammar is useful if, and only if, it makes your writing clearer. For example, you can use sentence fragments if they're self-explanatory. + +That said, a few rules help keep the docs concise, consistent, and clear: + +- Format headings in sentence case. Capitalize the first word and any proper nouns. All other words are lowercase. For example, `Set up authentication` rather than `Set Up Authentication`. +- Use the Oxford comma (a comma before the `and` that marks the last item in a list). For example, `realtime, database, and authentication` rather than `realtime, database and authentication`. +- Use the present tense as much as possible. For example, `the AI assistant answers your question` rather than `the AI assistant will answer your question`. + +## Word usage and spelling + +Use American English. If in doubt, consult the [Merriam-Webster dictionary](https://www.merriam-webster.com/). + +Here are some exceptions and Supabase-specific guidelines. + +### General word usage + +- **Filler words**: You can often make your writing more concise by removing these words. (Some of these words can also sound patronizing.) + - Actually + - Easy, easily + - Just + - Let's + - Please + - Simple, simply +- **UI elements** + - Buttons are `click`ed. + - Checkboxes are `select`ed. + - Toggles are `enable`d and `disable`d. + - Labels of UI elements are bolded. For example, `Click **Confirm**.` + +### Word list + +- `Backend` isn't hyphenated (not `back-end`). +- `Frontend` isn't hyphenated (not `front-end`). +- `Login` is a noun. `Log in` is a verb. +- `Postgres` is capitalized, except in code, and used instead of `PostgreSQL`. +- `Setup` is a noun. `Set up` is a verb. +- `Supabase` is capitalized (not `supabase`), except in code. +- `Supabase Platform` is in title case (not `Supabase platform`).