fix(about docs): update readme, contribution guide, and "about" secti…

…on (#6072)

* ran prettier format

* update contributing and readme mds

* move about docs around

* update docusaurus while I'm at it

CONTRIBUTING.md

@@ -1,19 +1,35 @@
 # Contributing to Prisma Documentation
 
-We welcome all contributions to the Prisma docs! If you come across some documentation that you feel is missing or incorrect, please open an issue or submit a pull request.
+Thank you for wanting to contribute to our docs! If you come across some documentation on [prisma.io/docs](https://www.prisma.io/docs) that you feel is missing or incorrect, please open an issue or submit a pull request.
 
-## I am not sure my changes are valid
+## New contributor guide
 
-If you are not sure your changes are valid, then please open an issue and we will discuss it. Contributions from community members are welcome and will be considered for inclusion.
+In general, we would recommend you first open an issue before submitting a pull request. In some cases, Prisma contributors may be able to describe the issue or offer a solution. If you would like to try and solve the issue yourself, please feel free to read [our README](./README.md), get set up with the docs repo, and submit a pull request.
 
-## Creating an issue
+### I am not sure my changes are valid
+
+If you are not sure your changes are valid, then please still open an issue and we will discuss it. Contributions from community members are welcome and will be considered for inclusion.
+
+### Creating an issue
 
 There are no hard and fast rules for creating an issues to the repository. We only ask that you outline your reasoning for creating the issue and try to provide as much detail as possible. Depending on the issue, this could mean explaining what machine you are working on (Is it a Mac? Are you on a Windows machine?), or including a code snippet that demonstrates the issue.
 
-## Creating a pull request (PR)
+If you spot a problem with the docs, [search if an issue already exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments). If a related issue doesn't exist, you can open a new issue using a relevant [issue form](https://github.com/github/docs/issues/new/choose).
+
+### Solving an issue
+
+Scan through our [existing issues](https://github.com/github/docs/issues) to find one that interests you. You can narrow down the search using `labels` as filters. See "[Label reference](https://docs.github.com/en/contributing/collaborating-on-github-docs/label-reference)" for more information. As a general rule, we don’t assign issues to anyone. If you find an issue to work on, you are welcome to open a PR with a fix.
 
-We have a pull request template. The basic breakdown is as follows:
+### Creating a pull request (PR)
+
+Similar to issues, we do not have hard and fast rules for Pull Requests. If you are opening a pull request we do ask that you:
 
 - Describe the reason for the PR. A little context goes a long way in helping to quickly scan the PR
 - Briefly describe what changes were made
 - Link to any relevant issues
+
+The Prisma team may ask for changes before a PR can be merged. As these changes are made, please mark the corresponding comments as "resolved". If you need help on a pull request or would like feedback, please feel free to mention the `@Dev-Connections` team.
+
+As a final note, if you're still working on a PR, please utilize the "Draft Pull Request" feature to let us know that your work is not yet ready. 
+
+Thank you again for contributing to our documentation!

README.md

@@ -33,6 +33,8 @@ To prettify or format the code, run:
 npm run format
 ```
 
+Please note that `.md` and `.mdx` files are not formatted by Prettier because they are written in [MDX 3](https://mdxjs.com/blog/v3/) which Prettier [does not support](https://github.com/prettier/prettier/issues/12209).
+
 Visit `http://localhost:3000` to view the app.
 
 ## Configure
@@ -125,23 +127,6 @@ $ mdtool remove 2
 # Result: 01-a, 02-b, 03-c, 04-d becomes 01-a, 02-b, 02-c, 03-d; 02-b is supposed to be manually deleted
 ```
 
-### Prettier
-
-To align with the current standards specified in our `.prettierc` configuration, it's recommended to include the `pre-commit` hook within the `/.github/` directory. This can be achieved by executing the following commands from the project's root:
-
-```bash
-mv /.github/pre-commit /.git/hooks/
-```
-
-After that, and upon executing a commit command, you may encounter the following message:
-
-```
-hint: The '.git/hooks/pre-commit' hook was ignored because it's not set as executable.
-hint: You can disable this warning with `git config advice.ignoredHook false`.
-```
-
-To address this, you can follow the provided instructions to disable the `ignoredHook` flag.
-
 #### Thanks Luca
 
 ![](https://res.cloudinary.com/prismaio/image/upload/v1628765536/docs/LJ0FGHk_u2jjxv.png)

content/600-about/200-prisma-docs/20-style-guide/01-writing-style.mdx → content/600-about/20-style-guide/01-writing-style.mdx

@@ -20,7 +20,7 @@ It's a good principle of technical communication to write as simply as possible.
 - English has many synonyms - where possible, choose the simplest available word for the job. Examples: "in" instead of "within", "use" instead of "utilize".
 - Use bullet lists to break up complex sentences into component points
 - Use examples
-- Use [appropriate text emphasis, such as bold and italics](/about/prisma-docs/style-guide/spelling-punctuation-formatting#text-emphasis) to make your writing clearer
+- Use [appropriate text emphasis, such as bold and italics](/about/style-guide/spelling-punctuation-formatting#text-emphasis) to make your writing clearer
 - Use tables to set out complex information
 - Use diagrams to make complex workflows or concepts easier to visualize
 

content/600-about/200-prisma-docs/20-style-guide/02-word-choice.mdx → content/600-about/20-style-guide/02-word-choice.mdx

@@ -134,7 +134,7 @@ We plan to remove `command name` in v.4.0.0.
 
 If you want to abbreviate a term, write it out fully first, then put the abbreviation in parentheses. After that, you can use the abbreviation for the rest of the page. For example, "In computer science, an abstract syntax tree (AST) is …".
 
-See also: [Jargon](/about/prisma-docs/style-guide/writing-style#jargon)
+See also: [Jargon](/about/style-guide/writing-style#jargon)
 
 ## Avoid ambiguous English words
 
@@ -326,4 +326,4 @@ You can choose to host your project in Vercel or Netlify.
 
 Use _checkbox_.
 
-See [Avoid excessive use of UI terminology](/about/prisma-docs/style-guide/user-interace-guidelines#avoid-excessive-use-of-ui-terminology).
+See [Avoid excessive use of UI terminology](/about/style-guide/user-interace-guidelines#avoid-excessive-use-of-ui-terminology).

content/600-about/200-prisma-docs/20-style-guide/03-spelling-punctuation-formatting.mdx → content/600-about/20-style-guide/03-spelling-punctuation-formatting.mdx

@@ -30,13 +30,15 @@ If you are in doubt about whether to emphasize some text, then don't do it.
 
 ### UI elements
 
-For the names of GUI elements (buttons, drop-down menus, and so on), use bold. Also use the same capitalization as in the GUI. For example:
+For the names of GUI elements (buttons, drop-down menus, and so on), use **bold**. Also use the same capitalization as in the GUI. For example:
 
-1. In the **File** menu, select **Open...**.
+1. In the `**File**` menu, select `**Open...**`.
 
 ### Avoid exclamation points
 
-In keeping with our calm tone, do not use exclamation points (exclamation marks). Exception: they are acceptable in congratulatory or welcome messages, for example: "Congratulations - you've completed the tutorial!"
+In keeping with our calm tone, do not use exclamation points (exclamation marks). 
+
+Exception: they are acceptable in congratulatory or welcome messages, for example: "Congratulations - you've completed the tutorial!"
 
 ### Capitalize and spell out proper nouns
 
@@ -54,7 +56,7 @@ If you're not sure about the spelling of a proper noun, check its official web s
 ### Titles and headings
 
 - Use sentence case for titles and headings: only the initial word is uppercase (exception: [capitalize proper nouns](#capitalize-and-spell-out-proper-nouns))
-- [Avoid gerunds](/about/prisma-docs/style-guide/word-choice#avoid-gerunds-ing-verb-forms) ("Configure the database", not "Configuring the database")
+- [Avoid gerunds](/about/style-guide/word-choice#avoid-gerunds-ing-verb-forms) ("Configure the database", not "Configuring the database")
 - Do not use punctuation at the end of a title or heading unless a question mark is required
 - Use ``code`` for code in headings - this is required by our navigation elements
 
@@ -156,22 +158,22 @@ Write a short introductory sentence that:
 
 For example:
 
-This [`createMany`](..) query does the following:
+This [`createMany()`](/orm/reference/prisma-client-reference/#createmany) query does the following:
 
 - Creates several `User` records
 - Creates several nested `Post` records
 - Creates several nested `Category` records
 
 ### Show the result of a query wherever possible
 
-Use the [`<CodeWithResult>`](/about/prisma-docs/docs-components/mdx-examples#code-with-result) component to show a query and the results of that query.
+Use the [`<CodeWithResult>`](/about/docs-components/mdx-examples#code-with-result) component to show a query and the results of that query.
 
-### Use the `highlight` property to highlight
+### Use `highlight` comments to highlight code
 
-Use the [`highlight` property](/about/prisma-docs/docs-components/mdx-examples#code-block-with-highlighted-code) if you need to highlight your code samples. For example:
+If you need to highlight lines in your code samples, use the [`highlight` magic comments](/about/docs-components/mdx-examples#code-block-with-highlighted-code). For example:
 
 ````
-```prisma highlight=3;normal
+```prisma
 generator client {
   provider        = "prisma-client-js"
   //highlight-next-line
@@ -210,20 +212,6 @@ datasource db {
 }
 ```
 
-### Use Prettier code formatting
-
-Install [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) in VSCode. Prettier helps ensure your code examples and Markdown have consistent formatting, such as line spacing and indentation.
-
-If you need to force Prettier to ignore a code block or section of Markdown, you can use `// prettier-ignore`:
-
-```js
-
-function xyz() {
- console.log({a, b})
-}
-
-```
-
 ### Use expressive variable names
 
 Good:
@@ -240,15 +228,15 @@ const results = (...) // Too generic
 const foo = (...) // Too vague
 ```
 
-### Strive for code snippets to be valid
+### Include valid code snippets
 
 Ensure that code snippets you include are realistic examples that would work if run in the context presented.
 
-### Prisma schema naming conventions
+### Follow Prisma Schema naming conventions
 
-When you create a Prisma schema for an example, follow the [naming conventions](/orm/reference/prisma-schema-reference#naming-conventions) we advise for users.
+When you create a Prisma Schema for an example, follow the [naming conventions](/orm/reference/prisma-schema-reference#naming-conventions) we advise for users.
 
-### Lists of shell commands
+### List shell commands in a single code block
 
 When you need to provide a series of CLI commands as instructions to the reader, use a single block. Don't use a list unless you want to provide context for each step:
 
@@ -275,9 +263,9 @@ or
 1. Migrate your database schema: `./node_modules/.bin/sequelize db:migrate` or `npx sequelize db:migrate`
 1. Seed the database: `./node_modules/.bin/sequelize db:seed:all` or `npx sequelize db:seed:all`
 
-### Don't prepend CLI commands with `$`
+### Don't prepend CLI commands in code blocks with `$`
 
-Use `terminal` for CLI commands - this type of code block includes a `$`:
+Use the `terminal` language meta string for CLI commands - this type of code block includes a `$`:
 
 ````
 ```terminal
@@ -291,28 +279,6 @@ For example:
 npm install prisma
 ```
 
-### npm vs Yarn
-
-Always use `npm` commands instead of `yarn`.
-
-### Error message reference
-
-The [error message reference](/orm/reference/error-reference) is a semi-generated doc. Do not edit the list of error codes manually. Use the script to generate the error codes.
+### Use `npm` as the default package manager
 
-When you bring the error messages into the page, remove any double quotes around them.
-
-Bad:
-
-```
-#### `P1008`
-
-"Operations timed out after `{time}`"
-```
-
-Good:
-
-```
-#### `P1008`
-
-Operations timed out after `{time}`
-```
+All examples should use `npm`. Other package manager options (`yarn`, `pnpm`, `bun`) should only be used if commands differ and never as the default.

content/600-about/200-prisma-docs/40-template.mdx → content/600-about/40-template.mdx

@@ -3,14 +3,9 @@ title: 'Writing template'
 metaTitle: 'Writing template (About)'
 description: 'A template for writing Prisma Docs.'
 toc_max_heading_level: 3
-hide_table_of_contents: false
 ---
 
-<TopBlock>
-
-A short introduction that encourages visitors to read on. The `TopBlock` component is not required in most cases, but is recommended.
-
-</TopBlock>
+A short introduction that encourages visitors to read on.
 
 ## A section
 

content/600-about/index.mdx

@@ -7,8 +7,29 @@ sidebar_position: 0
 sidebar_class_name: firstTitle
 ---
 
-<TopBlock>
+This section of our docs is about... the docs!
 
-</TopBlock>
+Here we describe how our docs are made and how we would prefer you contribute. Here are some handy links:
 
-<Subsections depth="3" />
+- [Our style guide](/about/style-guide) is a good place to start to learn about how we write our documentation and the tone we use.
+- [Our component guide](/about/docs-components) is great for understanding the React components that are available to you in our documentation.
+- [Our template](/about/template) is a starter template for a page of content.
+
+## The `User` and `Post` data model
+
+`User` and `Post` are the canonical models that are being used throughout the Prisma docs. The `User` and `Post` models have been selected for the following reasons:
+
+- These two models do not require domain-specific knowledge.
+- They are also commonly used as an example in the ORM space, making them familiar for users coming from other tools.
+- Having consistent models makes it easier for the reader when learning about different concepts, since there will be less context switching.
+- Less decision making and cognitive overhead for the docs authors. Using the same models reduces decision fatigue and is one less thing to worry about when trying to explain concepts.
+
+## Naming conventions for tables and columns
+
+Prisma ORM defaults to models (and therefore tables) formatted in [PascalCase](https://en.wikipedia.org/wiki/Camel_case) while fields (and therefore columns) are in [camelCase](https://en.wikipedia.org/wiki/Camel_case)
+
+## Embrace redundancy
+
+Meet the user where they are. If a piece of information needs to be described in multiple places, do so, but be sure to use [a markdown fragment](https://docusaurus.io/docs/markdown-features/react#importing-markdown) so that information can be updated in one place in the future.
+
+<Subsections />

lostpixel.config.ts

@@ -17,7 +17,7 @@ export const config: CustomProjectConfig = {
           display: none;
         }
         `,
-    })
+    });
   },
   lostPixelProjectId: "clb5ek3mm1772001qqg7yban38",
   apiKey: process.env.LOST_PIXEL_API_KEY,

package.json

@@ -12,10 +12,11 @@
     "clear": "docusaurus clear",
     "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
-    "write-heading-ids": "docusaurus write-heading-ids"
+    "write-heading-ids": "docusaurus write-heading-ids",
+    "format": "prettier --write ."
   },
   "dependencies": {
-    "@docusaurus/core": "^3.3.2",
+    "@docusaurus/core": "^3.4.0",
     "@docusaurus/preset-classic": "^3.4.0",
     "@mdx-js/react": "^3.0.0",
     "@react-aria/overlays": "^3.22.1",
@@ -34,7 +35,7 @@
     "sass": "^1.77.4"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^3.3.2",
+    "@docusaurus/module-type-aliases": "^3.4.0",
     "@docusaurus/tsconfig": "^3.4.0",
     "@docusaurus/types": "^3.4.0",
     "prettier": "3.3.0",