Doc changes (twentyhq#2106)

* refactored Storybook UI * refactored Storybook UI * removed extra cards from the doc, added card for ui components * added hover behavior to doc page & made it look selected * separate storybook docs and tests * separating storybook tests and docs * fixed spelling errors in docs * Final round of edits for frontend, added backend folder architecture * Created CODE_OF_CONDUCT.md * Add code of conduct to contributing.md
bkleiner · Oct 18, 2023 · 1cd91e6 · 1cd91e6
1 parent 51a06b3
commit 1cd91e6
Show file tree

Hide file tree

Showing 23 changed files with 202 additions and 51 deletions.
diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md
@@ -0,0 +1,73 @@
+# Contributor Code of Conduct
+
+## Our Pledge
+
+As contributors and maintainers of this project, we pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, friendly, 
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Respectfully giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment 
+* The use of aggressive language 
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders and maintainers of this repository are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders and maintainers of this repository have the right and responsibility to remove, edit, or reject
+comments, commits, code, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -69,11 +69,15 @@ git push origin branch-name
 
 <br>
 
+## Code of Conduct
 
-## Reporting Issues
+Please note that by contributing to this project, you are expected to follow our [Code of Conduct](./CODE_OF_CONDUCT.md). We strive to maintain a welcoming, friendly, and inclusive community for all contributors.  
+
+<br>
 
+## Reporting Issues
 
-If you encounter any issues or have suggestions for improvements, please feel free to create an issue on our GitHub repository. When reporting issues, please provide as much detail as possible to help us understand and address the problem effectively.
+If you encounter any issues or have suggestions for improvements, please feel free to (create an issue on our GitHub repository)[https://github.com/twentyhq/twenty/issues/new]. When reporting issues, please provide as much detail as possible to help us understand and address the problem effectively.
 
 ---
 

diff --git a/docs/docs/contributor/frontend/advanced/best-practices.mdx b/docs/docs/contributor/frontend/advanced/best-practices.mdx
@@ -188,7 +188,7 @@ const [email, setEmail] = useState('');
 
 ### Event handlers
 
-Event handler names should start with `handle`, while `on` is a prefix used to name events in components props
+Event handler names should start with `handle`, while `on` is a prefix used to name events in components props.
 
 ```tsx
 // ❌ Bad
@@ -237,7 +237,7 @@ const Form = () => <EmailField value="username@email.com" />;
 
 ## Component as props
 
-Try as much as possible to pass uninstanciated components as props, so children can decide on their own of what props they need to pass.
+Try as much as possible to pass uninstantiated components as props, so children can decide on their own of what props they need to pass.
 
 The most common example for that is icon components: 
 

diff --git a/docs/docs/contributor/frontend/advanced/style-guide.mdx b/docs/docs/contributor/frontend/advanced/style-guide.mdx
@@ -9,7 +9,7 @@ We define here the rules to follow when writing code.
 
 Our goal is to have a consistent codebase, which is easy to read and easy to maintain. 
 
-For this we prefer to tend towards being a bit more verbose than being too concise.
+For this we prefer being a bit more verbose than being too concise.
 
 Always keep in mind that code is read more often than it is written, especially on an open source project, where anyone can contribute.
 
@@ -134,7 +134,7 @@ onClick?.();
 
 ## TypeScript
 
-### Use `type` instead of `Interface`
+### Use `type` instead of `interface`
 
 We decided to always use `type` instead of `interface`, because they almost always overlap, and `type` is more flexible.
 
@@ -154,7 +154,7 @@ type MyType = {
 
 [String literals](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) are the go-to way to handle enum-like values in TypeScript. They are easier to extend with Pick and Omit, and offer a better developer experience, especially with code completion.
 
-You can see why TypeScript recommend avoiding enums [here](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#enums). 
+You can see why TypeScript recommends avoiding enums [here](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#enums). 
 
 ```tsx
 // ❌ Bad, utilizes an enum

diff --git a/docs/docs/contributor/frontend/basics/basics.mdx b/docs/docs/contributor/frontend/basics/basics.mdx
@@ -1,6 +1,5 @@
 ---
 title: Basics
-# description: Overview
 sidebar_position: 0
 sidebar_custom_props:
   icon: TbEyeglass
@@ -45,7 +44,7 @@ To avoid unnecessary [re-renders](/contributor/frontend/advanced/best-practices#
 
 We use [Recoil](https://recoiljs.org/docs/introduction/core-concepts) for state management.
 
-See our [best practices](/contributor/frontend/advanced/best-practices#state-management) for more managing state.
+See our [best practices](/contributor/frontend/advanced/best-practices#state-management) for more information on state management.
 
 ## Testing
 

diff --git a/docs/docs/contributor/frontend/basics/contributing.mdx b/docs/docs/contributor/frontend/basics/contributing.mdx
@@ -6,7 +6,7 @@ sidebar_custom_props:
   icon: TbTopologyStar
 ---
 
-## Pre-requesites
+## Pre-requisites
 
 Make sure that your [IDE is correctly setup](/contributor/local-setup/ide-setup) and that your backend is running on `localhost:3000`.
 

diff --git a/docs/docs/contributor/frontend/basics/folder-architecture.mdx b/docs/docs/contributor/frontend/basics/folder-architecture.mdx
@@ -17,7 +17,10 @@ front
 │   │   └───submodule1
 │   └───module2
 │   └───ui
-│   │   └───buttons
+│   │   └───display
+│   │   └───inputs
+│   │   │   └───buttons
+│   │   └───...
 └───pages
 └───...
 ```
@@ -29,7 +32,7 @@ Contains the top-level components that are defined by the application routes. Th
 ## Modules
 
 Each module represents a feature or a group of feature, comprising its specific components, states, and operational logic.
-They should all follow the structure below. You can nest modules within modules; We often refer to them as submodules but the same rules apply.
+They should all follow the structure below. You can nest modules within modules; we often refer to them as submodules but the same rules apply.
 
 ```
 module1
@@ -55,7 +58,7 @@ module1
 
 A context is a way to pass data through the component tree without having to pass props down manually at every level.
 
-See [React Context](https://react.dev/reference/react#context-hooks) for more details
+See [React Context](https://react.dev/reference/react#context-hooks) for more details.
 
 ### GraphQL
 
@@ -100,7 +103,7 @@ Should only contain reusable pure functions. Otherwise, create custom hooks in t
 
 Contains all of the reusable UI components used in the application.
 
-This folder can contain subfolders for specific types of components, such as `buttons`, `inputs`, or `modals`. Each component should be self-contained and reusable, so that it can be used in multiple parts of the application.
+This folder can contain subfolders, like `data`, `display`, `feedback`, and `input` for specific types of components. Each component should be self-contained and reusable, so that it can be used in multiple parts of the application.
 
 By separating the UI components from the other components in the `modules` folder, it is easier to maintain a consistent design and to make changes to the UI without affecting other parts (business logic) of the codebase.
 

diff --git a/docs/docs/contributor/frontend/basics/work-with-figma.mdx b/docs/docs/contributor/frontend/basics/work-with-figma.mdx
@@ -11,10 +11,16 @@ In this guide, we'll go over how to collaborate with Twenty’s Figma.
 
 ## Access
 
-1. **Access the shared link:** you can access the Twenty Figma file with this link: https://www.figma.com/file/xt8O9mFeLl46C5InWwoMrN/Twenty
+1. **Access the shared link:** You can access the Twenty Figma file [here](https://www.figma.com/file/xt8O9mFeLl46C5InWwoMrN/Twenty).
 2. **Sign in:** If you're not already signed in to Figma, you'll be prompted to do so. 
 Key features are only available to logged-in users, such as the developer mode and the ability to select a dedicated frame.
-**You will not be able to collaborate effectively without an account.**
+
+:::caution Note
+
+You will not be able to collaborate effectively without an account.
+
+:::
+
 
 ## Figma structure
 
@@ -30,18 +36,18 @@ With read-only access, you can't edit the design but you can access all features
 
 ### Use the Dev mode
 
-Figma's Dev Mode enhances developers' productivity by providing easy design navigation, effective asset management, efficient communication tools, toolbox integrations, quick code snippets, and key layer information, bridging the gap between design and development. Learn more at https://www.figma.com/dev-mode/
+Figma's Dev Mode enhances developers' productivity by providing easy design navigation, effective asset management, efficient communication tools, toolbox integrations, quick code snippets, and key layer information, bridging the gap between design and development. You can learn more about Dev Mode [here](https://www.figma.com/dev-mode/).
 
 Switch to the "Developer" mode in the right part of the toolbar to see design specs, copy CSS, and access assets. 
 
 ### Use the Prototype
 
-Click on any element on the canvas and press the “Play” button at the top right edge of the interface to access the prototype view.  Prototype mode allows you to interact with the design as if it were the final product. It demonstrates the flow between screens and how interface elements like buttons, links, or menus behave when interacted with.
+Click on any element on the canvas and press the “Play” button at the top right edge of the interface to access the prototype view. Prototype mode allows you to interact with the design as if it were the final product. It demonstrates the flow between screens and how interface elements like buttons, links, or menus behave when interacted with.
 
 1. **Understanding transitions and animations:** In the Prototype mode, any transitions or animations added by a designer between screens or UI elements can be viewed, providing clear visual instructions to developers on the intended behavior and style.
-2. **Implementation Clarification:** A prototype can also be used to reduce ambiguities. Developers can interact with it to gain a better understanding of the functionality or appearance of particular elements.
+2. **Implementation clarification:** A prototype can also be used to reduce ambiguities. Developers can interact with it to gain a better understanding of the functionality or appearance of particular elements.
 
-For more comprehensive details and guidance on learning the Figma platform, you can visit the official [Figma Documentation](https://help.figma.com/hc/en-us)
+For more comprehensive details and guidance on learning the Figma platform, you can visit the official [Figma Documentation](https://help.figma.com/hc/en-us).
 
 ### Measure distances
 

diff --git a/docs/docs/contributor/frontend/frontend.mdx b/docs/docs/contributor/frontend/frontend.mdx
@@ -1,7 +1,6 @@
 ---
 title: Frontend Development
 displayed_sidebar: frontendSidebar
-
 sidebar_position: 0
 sidebar_custom_props:
   icon: TbTerminal2

diff --git a/docs/docs/contributor/local-setup/docker-setup.mdx b/docs/docs/contributor/local-setup/docker-setup.mdx
@@ -27,10 +27,14 @@ You can run `docker --version` to verify the installation.
 
 ## Step 1: Git Clone
 
-In your terminal, run the following command. 
+In your terminal, run the following command:
+
+:::info Note
 
 We recommend using SSH for this step. If you already haven't set up SSH keys, please do so first. You can learn more about it [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh). 
 
+:::
+
 <Tabs>
 <TabItem value="ssh" label="SSH (Recommended)" default>
 

diff --git a/docs/docs/contributor/local-setup/ide-setup.mdx b/docs/docs/contributor/local-setup/ide-setup.mdx
@@ -6,7 +6,7 @@ sidebar_custom_props:
   icon: TbBrandVscode
 ---
 
-This section will help you set up your IDE for the project. If you haven't setup your development environment, please refer to our [local setup](/contributor/local-setup) section.
+This section will help you set up your IDE for the project. If you haven't set up your development environment, please refer to our [local setup](/contributor/local-setup) section.
 
 
 ## Visual Studio Code

diff --git a/docs/docs/contributor/local-setup/local-setup.mdx b/docs/docs/contributor/local-setup/local-setup.mdx
@@ -41,7 +41,7 @@ twenty
 
 ## IDE Setup
 
-Once Twnenty is running on your computer, you will get the best experience by using an IDE that supports TypeScript and ESLint.
+Once Twenty is running on your computer, you will get the best experience by using an IDE that supports TypeScript and ESLint.
 You will find a guide for [VSCode](/contributor/local-setup/ide-setup) further in the documentation.
 ___
 
diff --git a/docs/docs/contributor/local-setup/troubleshooting.mdx b/docs/docs/contributor/local-setup/troubleshooting.mdx
@@ -9,7 +9,7 @@ sidebar_custom_props:
 
 ## CR line breaks found [Windows]
 
-This is due to the linebreak characters of windows and the git configuration. Try running:
+This is due to the linebreak characters of Windows and the git configuration. Try running:
 ```
 git config --global core.autocrlf false
 ```
@@ -26,5 +26,5 @@ Try installing [yarn classic](https://classic.yarnpkg.com/lang/en/)!
 During Twenty installation, your postgres database needs to be provisioned with right schemas, extensions and users.
 We provide [different ways](/contributor/local-setup/yarn-setup#step-2-set-up-postgresql-database) to set up your postgres instance.
 
-If you sucessfully run this provisioning, you should have a `default` and a `metadata` schemas in your database.
+If you sucessfully run this provisioning, you should have `default` and `metadata` schemas in your database.
 If you don't, make sure you don't have multiple postgres instance running on your computer.
diff --git a/docs/docs/contributor/local-setup/wsl-setup.mdx b/docs/docs/contributor/local-setup/wsl-setup.mdx
@@ -38,7 +38,7 @@ Then, configure your git user name and email using the following commands, repla
 git config --global user.name "Your Name"
 git config --global user.email "youremail@domain.com"
 ```
-:::note
+:::info Note
 
 If you don't have a Github account, create one now with the corresponding email address. We recommend that you setup a SSH key for your Github account. Follow the instructions [here](https://docs.github.com/fr/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
 

diff --git a/docs/docs/contributor/local-setup/yarn-setup.mdx b/docs/docs/contributor/local-setup/yarn-setup.mdx
@@ -30,8 +30,12 @@ Before you can install and use Twenty, make sure you install the following on yo
 
 In your terminal, run the following command. 
 
+:::info Note
+
 We recommend using SSH for this step. If you already haven't set up SSH keys, please do so first. You can learn more about it [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh). 
 
+:::
+
 <Tabs>
 <TabItem value="ssh" label="SSH (Recommended)" default>
 
@@ -51,7 +55,7 @@ git clone https://github.com/twentyhq/twenty.git
 
 ## Step 2: Set up PostgreSQL Database
 You need to have a PostgreSQL instance available to be able to use Twenty.
-This database needs to be provisionned with the a `twenty` user (password: `twenty`), a `default` database and a `test` database.
+This database needs to be provisioned with a `twenty` user (password: `twenty`), a `default` database and a `test` database.
 
 <Tabs>
 <TabItem value="linux" label="Linux" default>
@@ -71,7 +75,7 @@ cd twenty
 make provision-postgres
 ```
 This will create a Docker container, exposing a PostgresSQL instance at [http://localhost:5432](http://localhost:5432).
-You can access them using `twenty` postgres user (password: `twenty`)
+You can access this using `twenty` postgres user (password: `twenty`)
   </TabItem>
   <TabItem value="mac-os" label="Mac OS" default>
 
@@ -91,18 +95,18 @@ cd twenty
 make provision-postgres
 ```
 This will create a Docker container, exposing a PostgresSQL instance at [http://localhost:5432](http://localhost:5432).
-You can access them using `twenty` postgres user (password: `twenty`)
+You can access this using `twenty` postgres user (password: `twenty`)
 
   </TabItem>
   <TabItem value="wsl" label="Windows (WSL)">
 
-We recommend to provision your database locally:
+We recommend that you provision your database locally:
 ```bash
 cd twenty
 bash ./infra/dev/scripts/setup-postgres-linux.sh
 ```
 This will create a Docker container, exposing a PostgresSQL instance at [http://localhost:5432](http://localhost:5432).
-You can access them using `twenty` postgres user (password: `twenty`)
+You can access this using `twenty` postgres user (password: `twenty`)
   </TabItem>
 </Tabs>