Improve documentation (twentyhq#82)

* Propose new doc architecture * Many improvements to documentation (styling, structure...) * Remove modules added inadvertently + continue improving styling * Swizzle navbar item to add support for custom icon * Additional doc styling * Setup docs for API and redirect homepage for docs
steebtom · Apr 26, 2023 · 42bf653 · 42bf653
1 parent 35cf3ee
commit 42bf653
Show file tree

Hide file tree

Showing 54 changed files with 2,597 additions and 703 deletions.
diff --git a/README.md b/README.md
@@ -1,69 +1,16 @@
 # Twenty
 
-Welcome to Twenty documentation!
+Twenty is a open source CRM designed to solve the issues that are still prevalent amongst the existings solutions. 
+It is meant to be:
+- Easily extendable
+- Perfectly in-sync with your data
+- Crafted with care and enjoyable to use
 
-## High Level Overview
+![Mockup of the CRM](/docs/src/img/mockup.png)
 
-Twenty development stack is composed of 3 different layers
 
-- front: our frontend React app
-- hasura: our graphql engine exposing our database and server
-- server: our backend that contain endpoint, crm logic, scripts, jobs...
-- storages: postgres
+# Documentation
+The doc is available on [docs.twenty.com](docs.twenty.com)
 
-## Setup env variables and npmrc variables
-
-1. `cp ./infra/dev/.env.example ./infra/dev/.env` and fill with values
-2. `cp ./front/.npmrc.example ./front/.npmrc` and fill with values
-
-## Development environment setup with docker-compose (Recommended)
-
-We also provide a containerized environment with Docker and orchestrated with docker-compose in case it is easier for you. This install will also provision a postgres container out of the box.
-
-### Step 1: pre-requesites
-
-Make sure to have the latest Docker and Docker-compose versions installed on your computer. You can run `docker-compose --version` to check if you have docker-compose installed and `docker --version` to check if you have docker installed.
-
-### Step 2: docker build
-
-Build docker containers.
-
-The whole setup experience is happening in `infra/dev` folder. Make sure to be in this folder:
-
-```
-cd infra/dev
-```
-
-```
-make build
-make up
-```
-
-Once this is completed you should have:
-
-- front available on: http://localhost:3001
-- hasura available on: http://localhost:8080
-- server available on: http://localhost:3000/health
-- postgres: available on http://localhost:5432 that should contain `twenty` database
-
-### Step 3: IDE setup
-
-If you are using VSCode, please use the `Dev Containers` extension to open the project in a container. This will allow you to run Visual Studio on top of the docker container. This will allow you to run the project without having to install node on your machine.
-
-### Note
-
-If you are using Docker install, make sure to ssh in the docker container during development to execute commands. You can also use `Makefile` to help you
-
-## Development workflow
-
-### Front tests
-
-Run tests: `make front-test`
-Run coverage: `make front-coverage`
-Run storybook: `make front-storybook`
-
-### Hasura development
-
-Open hasura console: `make hasura-console`
-Do your changes in hasura console on http://localhost:9695
-Commit your changes in git
+We don't have a Slack community yet but we will create one when we are ready to launch.
+In the meantime, feel free to create a Github issue or open a discussion.
diff --git a/docs/docs/dev-docs/data/README.mdx b/docs/docs/dev-docs/data/README.mdx
@@ -0,0 +1 @@
+# Data layer
diff --git a/docs/docs/dev-docs/data/_category_.json b/docs/docs/dev-docs/data/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Data layer",
+  "position": 3
+}
diff --git a/docs/docs/dev-docs/data/connect.mdx b/docs/docs/dev-docs/data/connect.mdx
@@ -0,0 +1 @@
+# Connecting to data sources
diff --git a/docs/docs/dev-docs/data/mapping.mdx b/docs/docs/dev-docs/data/mapping.mdx
@@ -0,0 +1 @@
+# Mapping entities
diff --git a/docs/docs/dev-docs/data/optimization.mdx b/docs/docs/dev-docs/data/optimization.mdx
@@ -0,0 +1 @@
+# Caching and optimization
diff --git a/docs/docs/dev-docs/development/README.mdx b/docs/docs/dev-docs/development/README.mdx
@@ -0,0 +1,4 @@
+
+# Translate your site
+
+Let's translate `docs/intro.md` to French.
diff --git a/docs/docs/dev-docs/development/_category_.json b/docs/docs/dev-docs/development/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Development",
+  "position": 2
+}
diff --git a/docs/docs/dev-docs/development/architecture.mdx b/docs/docs/dev-docs/development/architecture.mdx
@@ -0,0 +1 @@
+# Architecture
diff --git a/docs/docs/dev-docs/development/core-entities.mdx b/docs/docs/dev-docs/development/core-entities.mdx
@@ -0,0 +1 @@
+# Core entities
diff --git a/docs/docs/dev-docs/getting-started/_category_.json b/docs/docs/dev-docs/getting-started/_category_.json
@@ -1,8 +1,4 @@
 {
-  "label": "Tutorial - Basics",
-  "position": 2,
-  "link": {
-    "type": "generated-index",
-    "description": "5 minutes to learn the most important Docusaurus concepts."
-  }
+  "label": "Getting started",
+  "position": 1
 }
diff --git a/docs/docs/dev-docs/getting-started/cloud-setup.mdx b/docs/docs/dev-docs/getting-started/cloud-setup.mdx
@@ -0,0 +1 @@
+# Cloud setup
diff --git a/docs/docs/dev-docs/getting-started/congratulations.md b/docs/docs/dev-docs/getting-started/congratulations.md
diff --git a/docs/docs/dev-docs/getting-started/create-a-blog-post.md b/docs/docs/dev-docs/getting-started/create-a-blog-post.md
diff --git a/docs/docs/dev-docs/getting-started/create-a-document.md b/docs/docs/dev-docs/getting-started/create-a-document.md
diff --git a/docs/docs/dev-docs/getting-started/create-a-page.md b/docs/docs/dev-docs/getting-started/create-a-page.md
diff --git a/docs/docs/dev-docs/getting-started/deploy-your-site.md b/docs/docs/dev-docs/getting-started/deploy-your-site.md
diff --git a/docs/docs/api/intro.md → docs/docs/dev-docs/getting-started/index.mdx b/docs/docs/api/intro.md → docs/docs/dev-docs/getting-started/index.mdx
diff --git a/docs/docs/dev-docs/getting-started/local-setup.mdx b/docs/docs/dev-docs/getting-started/local-setup.mdx
@@ -0,0 +1,74 @@
+---
+sidebar_position: 0
+slug: '/'
+---
+
+# Twenty
+
+Welcome to Twenty documentation!
+
+## High Level Overview
+
+Twenty development stack is composed of 3 different layers
+
+- front: our frontend React app
+- hasura: our graphql engine exposing our database and server
+- server: our backend that contain endpoint, crm logic, scripts, jobs...
+- storages: postgres
+
+## Setup env variables and npmrc variables
+
+1. `cp ./infra/dev/.env.example ./infra/dev/.env` and fill with values
+2. `cp ./front/.npmrc.example ./front/.npmrc` and fill with values
+
+## Development environment setup with docker-compose (Recommended)
+
+We also provide a containerized environment with Docker and orchestrated with docker-compose in case it is easier for you. This install will also provision a postgres container out of the box.
+
+### Step 1: pre-requesites
+
+Make sure to have the latest Docker and Docker-compose versions installed on your computer. You can run `docker-compose --version` to check if you have docker-compose installed and `docker --version` to check if you have docker installed.
+
+### Step 2: docker build
+
+Build docker containers.
+
+The whole setup experience is happening in `infra/dev` folder. Make sure to be in this folder:
+
+```
+cd infra/dev
+```
+
+```
+make build
+make up
+```
+
+Once this is completed you should have:
+
+- front available on: http://localhost:3001
+- hasura available on: http://localhost:8080
+- server available on: http://localhost:3000/health
+- postgres: available on http://localhost:5432 that should contain `twenty` database
+
+### Step 3: IDE setup
+
+If you are using VSCode, please use the `Dev Containers` extension to open the project in a container. This will allow you to run Visual Studio on top of the docker container. This will allow you to run the project without having to install node on your machine.
+
+### Note
+
+If you are using Docker install, make sure to ssh in the docker container during development to execute commands. You can also use `Makefile` to help you
+
+## Development workflow
+
+### Front tests
+
+Run tests: `make front-test`
+Run coverage: `make front-coverage`
+Run storybook: `make front-storybook`
+
+### Hasura development
+
+Open hasura console: `make hasura-console`
+Do your changes in hasura console on http://localhost:9695
+Commit your changes in git
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,4 @@

		# Translate your site

		Let's translate `docs/intro.md` to French.