Improved user guide, added CI vale for docs (#2308)

* restructured user guide, minor fixes

* added index file for user guide

* github actions for vale

* testing workflow

* CI vale

* changes as per vale's suggestions

* set CI vale on pull request

* adding homebrew script to macos infra setup file

* fix CI errors

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* testing vale

* vale testing complete

* vale cleanup

* vale test

* vale test for github-pr-check

* vale test for github-pr-check

* vale test for github-pr-check

* vale test for github-pr-check

* testing vale warnings

* testing vale warnings

* testing vale warnings

* testing vale warnings

* testing vale warnings

* testing vale warnings

* testing vale warnings

* swizzled doc cards to add icons

* Align CI params to other CIs

---------

Co-authored-by: Félix Malfait <felix.malfait@gmail.com>

.github/SECURITY.md

@@ -22,7 +22,7 @@ While we don't currently have a formal bug bounty program due to the project's n
 
 ## Security Features
 We are always looking for ways to improve our product's security.
-If you have any recommendations or feature request that could enhance the product's security, we invite you to share them with us via the dicsussion forum.
+If you have any recommendations or feature request that could enhance the product's security, we invite you to share them with us via the discussion forum.
 
 ⚠️ Note this does not apply to security vulnerabilities. If you're in doubt, then always follow the security vulnerability process
 

.github/styles/docs/Acronyms.yml

@@ -12,6 +12,8 @@ exceptions:
   - ASP
   - CLI
   - CPU
+  - CMS
+  - CRM
   - CSS
   - CSV
   - DEBUG
@@ -22,6 +24,7 @@ exceptions:
   - GDB
   - GET
   - GPU
+  - GQL
   - GTK
   - GUI
   - HTML
@@ -36,6 +39,7 @@ exceptions:
   - NET
   - NOTE
   - NVDA
+  - ORM
   - OSS
   - PATH
   - PDF
@@ -58,6 +62,7 @@ exceptions:
   - URL
   - USB
   - UTF
+  - WSL
   - XML
   - XSS
   - YAML

.github/styles/docs/We.yml

@@ -1,6 +1,6 @@
 extends: existence
 message: "Avoid using first-person plural like '%s'."
-level: error
+level: warning
 ignorecase: true
 tokens:
   - we

.github/workflows/ci-vale.yaml

@@ -0,0 +1,22 @@
+name: CI-Vale
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+jobs:
+  vale:
+    name: runner / vale
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: errata-ai/vale-action@reviewdog
+        with:
+          files: ${{ steps.directories.outputs.LIST }}
+          fail_on_error: true
+          vale_flags: '--minAlertLevel=error'
+          reporter: github-pr-check
+          token: ${{ github.token }}
+          filter_mode: nofilter
+        env:
+          REVIEWDOG_GITHUB_API_TOKEN: ${{ github.token }}

.vale.ini

@@ -1,4 +1,4 @@
-StylesPath = docs/vale/styles
+StylesPath = .github/styles
 
 MinAlertLevel = suggestion
 
@@ -6,6 +6,11 @@ Packages = write-good
 
 [*.{md,mdx}]
 BasedOnStyles = Vale, write-good, docs
+Vale.Spelling=warning
+write-good.E-Prime=No
+write-good.So=No
+write-good.ThereIs=No
+Vale.Terms=No
 
 
 [formats]

docs/docs/contributor/frontend/advanced/style-guide.mdx

@@ -86,7 +86,7 @@ const EmailField = ({ value }: EmailFieldProps) => (
 
 #### No Single Variable Prop Spreading in JSX Elements
 
-We discourage the use of single variable prop spreading in JSX elements, e.g., `{...props}`. This practice often leads to less readable and maintainable code as it's unclear what props are being passed down to the component.
+We discourage the use of single variable prop spreading in JSX elements, like `{...props}`. This practice often leads to less readable and maintainable code as it's unclear what props are being passed down to the component.
 
 ```tsx
 /* ❌ - Bad, spreads a single variable prop into the underlying component

docs/docs/contributor/local-setup/troubleshooting.mdx

@@ -23,8 +23,8 @@ Try installing [yarn classic](https://classic.yarnpkg.com/lang/en/)!
 
 ## Missing metadata schema
 
-During Twenty installation, your postgres database needs to be provisioned with right schemas, extensions and users.
+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 `default` and `metadata` schemas in your database.
+If you successfully 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.

docs/docs/developer/graphql_api.mdx

@@ -11,7 +11,7 @@ Use our [in-browser GraphiQL app](https://docs.twenty.com/graphql/) to browse, q
 
 GraphQL is a query language for APIs that enables declarative data fetching that allows a client to specify exactly what data it needs from the API.
 
-Instead of exposing various endpoints that return fixed data strcutures, GraphQL exposes only a single endpoint that precisely returns the data that the client asked for. This makes GraphQL more flexible and efficient than other kinds of APIs, like REST APIs. 
+Instead of exposing various endpoints that return fixed data structures, GraphQL exposes only a single endpoint that precisely returns the data that the client asked for. This makes GraphQL more flexible and efficient than other kinds of APIs, like REST APIs. 
 
 To learn more about GraphQL, we recommend going through this [Introduction](https://www.howtographql.com/basics/0-introduction/).
 

docs/docs/others/bug-and-requests.mdx

@@ -6,7 +6,7 @@ sidebar_custom_props:
 ---
 
 ## Reporting Bugs
-To report a bug, please [create an issue on Github](https://github.com/twentyhq/twenty/issues/new).
+To report a bug, please [create an issue on GitHub](https://github.com/twentyhq/twenty/issues/new).
 
 ## Feature Requests
 

docs/docs/user-guide/basics/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Basics",
+  "position": 1
+}

docs/docs/user-guide/basics/custom objects.mdx

@@ -24,6 +24,7 @@ To create a new custom object:
 </div>
 
 <br/>
+
 3. Click on `+ New object` at the top, then choose Custom as the object type. Enter the name (both singular and plural) and description for your custom object and hit Save (at the top right). Using Listing as an example of custom object, the singular would be "listing" and the plural would be "listings" along with a description like "Listings that hosts created to showcase their property." 
 
 <br/>

docs/docs/user-guide/integrations/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Integrations",
+  "position": 2
+}

docs/docs/user-guide/others/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Others",
+  "position": 3
+}

docs/docs/user-guide/others/glossary.mdx

@@ -12,8 +12,8 @@ They are the two fundamental types of records that the CRM is built around:
 
 ### Pipelines
 A `Pipeline` is a way to track a business process. Pipelines are categorized within a *module* and have *stages*:
-- A **module** contains the logic for a certain business process (e.g. sales, recruiting).
-- **Stages** map the steps in your process (e.g. new, ongoing, won, lost).
+- A **module** contains the logic for a certain business process (for example: sales, recruiting).
+- **Stages** map the steps in your process (for example: new, ongoing, won, lost).
 
 ### Workspace
 A `Workspace` usually represents a company using Twenty.  

docs/docs/user-guide/user-guide.mdx

@@ -8,4 +8,30 @@ sidebar_custom_props:
   isSidebarRoot: true
 ---
 
-Coming soon!
+# Welcome to Twenty's User Guide
+
+This user guide is intended to help you learn how you can use Twenty to build the CRM you want. 
+
+In this quick-start guide, we'll walk you through the basics.
+
+## Quick Search 
+
+You'll see a search bar at the top of your sidebar. You can also bring up the command bar with the `cmd`/`ctrl` + `k` shortcut to quickly navigate through your workspace, and find people, companies, notes, and more. 
+
+The command bar also supports numerous shortcuts for navigation.  
+
+## Create Pre-filtered Views 
+
+Twenty allows you to add filters to see data that meets certain criteria and hides the rest. 
+
+To create a filter in your workspace, click Filter at the top right and select the attribute you'd like to filter your records by. Create your filter and then save changes in a new view by clicking `+ Create view`. 
+
+The filtered view is now available to your whole team.
+
+## Add Stages For Opportunities
+
+You can also add more stages to the opportunities board. 
+
+On the Opportunities page, click on Options, Stages, then `+ Add Stage`.
+
+You can also edit the stage by clicking on the name. 

docs/src/theme/DocCard/index.js

@@ -0,0 +1,97 @@
+import React from 'react';
+import clsx from 'clsx';
+import Link from '@docusaurus/Link';
+import {
+  findFirstCategoryLink,
+  useDocById,
+} from '@docusaurus/theme-common/internal';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+import {translate} from '@docusaurus/Translate';
+import styles from './styles.module.css';
+import * as icons from "../icons"; 
+
+
+function CardContainer({href, children}) {
+  return (
+    <Link
+      href={href}
+      className={clsx('card padding--lg', styles.cardContainer)}>
+      {children}
+    </Link>
+  );
+}
+function CardLayout({href, icon, title, description}) {
+  return (
+    <CardContainer href={href}>
+      <h2 className={clsx("text--truncate", styles.cardTitle)} title={title}>
+        <span className={styles.icon}>
+          {typeof icon === "function" ? icon() : icon}
+        </span>{" "}
+        {title}
+      </h2>
+      {description && (
+        <p
+          className={clsx("text--truncate", styles.cardDescription)}
+          title={description}
+        >
+          {description}
+        </p>
+      )}
+    </CardContainer>
+  );
+}
+
+function CardCategory({item}) {
+  const href = findFirstCategoryLink(item);
+  // Unexpected: categories that don't have a link have been filtered upfront
+  if (!href) {
+    return null;
+  }
+  return (
+    <CardLayout
+      href={href}
+      icon="🗃️"
+      title={item.label}
+      description={
+        item.description ??
+        translate(
+          {
+            message: '{count} items',
+            id: 'theme.docs.DocCard.categoryDescription',
+            description:
+              'The default description for a category card in the generated index about how many items this category includes',
+          },
+          {count: item.items.length},
+        )
+      }
+    />
+  );
+}
+
+
+function CardLink({ item }) {
+  const customIcon = item.customProps.icon;
+  const icon = icons[customIcon] || (isInternalUrl(item.href) ? "📄️" : "🔗");
+  const doc = useDocById(item.docId ?? undefined);
+
+  return (
+    <CardLayout
+      href={item.href}
+      icon={icon}
+      title={item.label}
+      description={item.description ?? doc?.description}
+    />
+  );
+}
+
+
+export default function DocCard({item}) {
+  switch (item.type) {
+    case 'link':
+      return <CardLink item={item} />;
+    case 'category':
+      return <CardCategory item={item} />;
+    default:
+      throw new Error(`unknown item type ${JSON.stringify(item)}`);
+  }
+}

docs/src/theme/DocCard/styles.module.css

@@ -0,0 +1,33 @@
+.cardContainer {
+  --ifm-link-color: var(--ifm-color-emphasis-800);
+  --ifm-link-hover-color: var(--ifm-color-emphasis-700);
+  --ifm-link-hover-decoration: none;
+
+  box-shadow: 0 1.5px 3px 0 rgb(0 0 0 / 15%);
+  border: 1px solid var(--ifm-color-emphasis-200);
+  transition: all var(--ifm-transition-fast) ease;
+  transition-property: border, box-shadow;
+}
+
+.cardContainer:hover {
+  border-color: var(--ifm-color-primary);
+  box-shadow: 0 3px 6px 0 rgb(0 0 0 / 20%);
+}
+
+.cardContainer *:last-child {
+  margin-bottom: 0;
+}
+
+.cardTitle {
+  font-size: 1.2rem;
+    display: flex
+}
+
+.cardDescription {
+  font-size: 0.8rem;
+}
+
+.icon {
+  font-size: 1.5rem;
+  padding-right: 0.5rem;
+}

infra/dev/scripts/setup-postgres-macos.sh

@@ -55,6 +55,7 @@ current_directory=$(pwd)
 
 # Install PostgresSQL
 echo_header $GREEN "Step [1/4]: Installing PostgreSQL..."
+
 brew install postgresql@$PG_MAIN_VERSION
 
 # Install pg_graphql extensions
@@ -96,6 +97,12 @@ rm -rf "$temp_dir"
 
 # Start postgresql service
 echo_header $GREEN "Step [3/4]: Starting PostgreSQL service..."
+
+if ! command -v brew &> /dev/null; then
+    echo_header $RED "Warning: Homebrew is not found in your PATH. Adding it to PATH..."
+    export PATH="/opt/homebrew/bin:$PATH"
+fi 
+
 if brew services start postgresql@$PG_MAIN_VERSION; then
     echo "PostgreSQL service started successfully."
 else