Improve documentation (#349)

* Improve documentation content
* Improve documentation style

docs/docs/dev-docs/development/README.mdx

@@ -1,4 +0,0 @@
-
-# Translate your site
-
-Let's translate `docs/intro.md` to French.

docs/docs/dev-docs/getting-started/index.mdx

@@ -1,25 +0,0 @@
-# Documentation
-
-
-# Stack Overview
-
-import ThemedImage from '@theme/ThemedImage';
-
-<ThemedImage
-  alt="Docusaurus themed image"
-  sources={{
-    light: '/img/architecture.png',
-    dark: '/img/architecture-dark.png',
-  }}
-/>
-
-
-# Quick Install
-
-```
-npx twenty-cli
-```
-
-# Questions, reports
-
-Please open an issue or a discussion on the [GitHub repository](https://github.com/twenyhq/twenty).

docs/docs/dev-docs/others/troubleshooting.mdx

@@ -1,8 +0,0 @@
----
-sidebar_custom_props:
-  icon: TbBug
----
-# Troubleshooting
-
-## Reporting bugs
-Please create an issue on Github: [https://github.com/twentyhq/twenty/issues/new](https://github.com/twentyhq/twenty/issues/new)

docs/docs/dev/architecture.mdx

@@ -9,9 +9,9 @@ sidebar_custom_props:
 import ThemedImage from '@theme/ThemedImage';
 
 <ThemedImage
-  alt="Docusaurus themed image"
+  alt="App Architecture"
   sources={{
-    light: '/img/architecture.png',
+    light: '/img/architecture-light.png',
     dark: '/img/architecture-dark.png',
   }}
 />

docs/docs/dev/glossary.mdx

@@ -0,0 +1,19 @@
+---
+sidebar_custom_props:
+  icon: TbVocabulary
+---
+# Glossary
+
+### Workspace
+A workspace usually represents a company using Twenty.  
+It's attached to a single domain name, which is usually the domain name you company uses for your employee email addresses.
+
+### Company & People
+They are the two fundamental type of records that the CRM is built around.  
+A company represents a business or an organization. And People represents an individual you are doing business with or would like to do business with.
+
+### Pipelines
+A pipeline is a way to track a business process.  
+Pipelines are categorized within a module and have stages.  
+A module is the business characterizations of your process (e.g. sales, recruiting).  
+Stages maps the steps in your process (e.g. new, ongoing, won, lost)

docs/docs/index.mdx

@@ -0,0 +1,37 @@
+---
+sidebar_position: 0
+hide_title: true
+sidebar_class_name: display-none
+title: Welcome
+custom_edit_url: null
+---
+import ThemedImage from '@theme/ThemedImage';
+
+# Introduction
+
+Twenty is an Open Source CRM.
+<ThemedImage sources={{light: "./img/preview-docs-light.png", dark:"./img/preview-docs-dark.png"}} style={{width:'100%', maxWidth:'800px'}}/>
+
+
+## Why did we create Twenty?
+At first, CRM platforms were just for sales teams.
+But now, they've grown to cover more than just sales - they handle many aspects of running a business.
+This has often left in-house engineering teams out of the loop, making companies rely more on outside help to manage their CRM needs.
+
+Our team has a shared passion for crafting beautiful product with great attention to details.
+And we are starting this project with one key goal: to put the power back in the hands of the people who use CRM systems every day.
+We wish to create a tool that users will enjoy, and that engineers will want to make their own and customize for their company's specific needs.
+
+## Getting started
+
+There are three ways for you to get started which are documented in the left sidebar:
+- **Cloud:** the fastest and easiest way to try the app (it's free)
+- **Local:** if you're a developer and would like to experiment or contribute to the app
+- **Self-hosting:** if you want greater control over your data and to run the app on your own server
+
+## Contributing
+Contributions are what makes the open source community such an amazing place.  
+Code contributions through pull request are most welcome.
+But it doesn't have to be code. You can also create an issue to report a bug you've spotted, join discussions or write documentation.
+
+

docs/docs/others/troubleshooting.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_custom_props:
+  icon: TbBug
+---
+# Troubleshooting
+
+## Reporting bugs
+Please create an issue on Github: [https://github.com/twentyhq/twenty/issues/new](https://github.com/twentyhq/twenty/issues/new)
+
+If you're not sure it's a bug and you feel it's closer to a feature request, then you should probably open a discussion instead: 
+[https://github.com/twentyhq/twenty/discussions/new](https://github.com/twentyhq/twenty/discussions/new)

docs/docs/start/local-setup.mdx

@@ -1,45 +1,40 @@
 ---
 sidebar_position: 0
-slug: '/'
 sidebar_custom_props:
   icon: TbBolt
 ---
 
 # Local Setup
 
-## Quickstart CLI
+We recommend using Docker to avoid potential problems with version compatibility, but it's also fairly simple to run the app directly on your machine.
 
-We built a CLI to guide you through the different options.
-
-If you prefer to have more control and do things manually, go through the Docker section below.
-
-Otherwise run the following command to get started:
-```
-npx twenty-cli
-```
-
-
-## Docker
+## With Docker
 
 ### 1. Pre-requisites
 
-Make sure to have the latest Docker and Docker-compose versions installed on your computer.
+Make sure you have the latest Docker and Docker-compose versions installed on your computer.
 
 You can run `docker-compose --version` and `docker --version` to check they are installed.
 
 ### 2. Git clone
-`git clone git@github.com:twentyhq/twenty.git`
+```
+git clone git@github.com:twentyhq/twenty.git
+```
 
 ### 3. Setup env variables
 
-`cp ./infra/dev/.env.example ./infra/dev/.env` and fill with values
-`cp ./front/.env.example ./front/.env` and fill with values
-`cp ./server/.env.example ./server/.env` and fill with values
+Go to the cloned folder (`cd twenty`). Then copy the env files:
+```
+cp ./infra/dev/.env.example ./infra/dev/.env
+cp ./front/.env.example ./front/.env
+cp ./server/.env.example ./server/.env 
+```
+Default values should work out of the box with the docker setup.
 
 ### 4. Build
 
 We provide a containerized environment with Docker and orchestrated with docker-compose.
-This install will also provision a postgres container out of the box.
+This install will also provision a Postgres container.
 
 The configuration is stored `infra/dev` folder. 
 
@@ -57,14 +52,14 @@ We will add an easier option soon.
 
 Before running the project, we need to apply database init and migrations and run the seed.
 
-Always in the `infra/dev` folder.
+Always go the `infra/dev` folder to run the `make` commands.
 
-Run the containers:
+Start the containers:
 ```
 make up
 ```
 
-Generate database init and migrations:
+Run database migrations:
 ```
 make server-prisma-migrate
 ```
@@ -95,26 +90,33 @@ make-server start
 
 - front available on: http://localhost:3001
 - server available on: http://localhost:3000/healthz
-- postgres: available on http://localhost:5432 that should contain `twenty` database
+- postgres: available on http://localhost:5432 and should contain database named `twenty` 
 
 
 ### 8. Development
 
-Documented [here](../development/workflows.mdx)
+Documented [here](../dev/workflows.mdx)
 
-## Without Docker (Not recommended)
+## Without Docker
 
-While Docker is the recommended way to run Twenty, you might want to keep a light install.
+While Docker is the recommended way to run Twenty, you might want to run the project directly on your machine.
 
 ### 1. Pre-requisites
-You need to have git, node and npm install on your computer.
+You need to have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), [node](https://nodejs.org/en/download) and [yarn](https://classic.yarnpkg.com/lang/en/docs/install/) installed on your computer.
 You also need to bring your own Postgres database.
 
 ### 2. Git clone
-`git clone git@github.com:twentyhq/twenty.git`
+```
+git clone git@github.com:twentyhq/twenty.git
+```
 
 ### 3. Setup env variables
-`cp ./infra/dev/.env.example ./infra/dev/.env` and fill with values 
+Make a copy of .env.example files:
+```
+cp ./front/.env.example ./front/.env
+cp ./server/.env.example ./server/.env
+```
+
 Most default value should work out of the box, but don't forget to update the database connection string.
 
 ### 4. Build
@@ -130,7 +132,7 @@ cd server
 yarn
 yarn prisma:migrate
 ```
-You can also add `yarn prisma:seed` to seed the database with mock data.
+You can also run `yarn prisma:seed` to seed the database with mock data.
 
 ### 5. Auth Setup
 Right now the only way to authenticate yourself is to setup Google Sign-in in `server/.env`

docs/docs/user-guide/intro.md

@@ -1,3 +0,0 @@
-# User Guide
-
-We didn't take the time to write a user-guide yet, but it will come soon.