Improve documentation (#349)

* Improve documentation content
* Improve documentation style

README.md

@@ -29,32 +29,37 @@
 </p>
 
 # About
-
-Twenty is an Open Source CRM designed to solve the issues that are still prevalent among the existings solutions. 
-It is meant to be:
+Twenty is an Open Source CRM designed to be:
 - Easily extendable
 - Perfectly in-sync with your data
 - Crafted with care and enjoyable to use
 
+# Helping us
+- The easiest way to help us is to star the repo and helping us getting visibility
+- Contributions are, of course, most welcome! It doesn't have to be code, you could also create an issue to report a bug you've spotted, join discussions or write documentation.
+
 # Quickstart
-No need to clone the repo, just run `npx twenty-cli` in your terminal and follow the instructions.
+By the first week of July, you should be able to try a demo directly on [app.twenty.com](https://app.twenty.com), our cloud offering with a generous free tier. We'll also release click-to-deploy buttons for Render and Railway.
+
+In the meantime, you can check [the documentation](/start/local-setup). It shouldn't take more than a few minutes to install locally.
 
 # Progress
 We are currently in the development phase of Twenty's alpha version:
 
-**Released**<br>
-✅  Create Companies & People<br>
-✅  View, filter and sort Companies & People<br>
+**Released**  
+✅  Create Companies & People  
+✅  View, filter and sort Companies & People  
+✅  Comments  
 
-**In development**<br>
-⚙️  Pipe views (Opportunities)<br>
-⚙️  Comments<br>
+**In development**  
+⚙️  Pipelines  
+⚙️  Custom Fields  
 
-**Planned**<br>
-📅  Email logging<br>
-📅  Custom Fields<br>
-📅  Search / Cmd + K<br>
-📅  Data connexion<br>
+**Planned** 
+📅  Activity log  
+📅  Auto-logging emails  
+📅  Search / Cmd + K  
+📅  Data connectors  
 📅  +++
 
 # Documentation

docs/README.md

@@ -1,4 +1,5 @@
 # Documentation
 
 The docs here are managed through [Docusaurus 2](https://docusaurus.io/).
-We recommend you go directly to the [staticly generated website](https://docs.twenty.com) rather than read them here.
+
+We recommend you go directly to the [statically generated website](https://docs.twenty.com) rather than read them here.

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.

docs/docusaurus.config.js

@@ -38,8 +38,7 @@ const config = {
           sidebarPath: require.resolve('./sidebars.js'),
           sidebarCollapsible: false,
           routeBasePath: '/',
-          editUrl:
-            'https://github.com/twentyhq/twenty/edit/main/docs/docs/',
+          editUrl: 'https://github.com/twentyhq/twenty/edit/main/docs/docs/',
         },
         blog: false,
         theme: {
@@ -67,18 +66,6 @@ const config = {
             type: 'search',
             position: 'left',
           },
-          {
-            type: 'docSidebar',
-            sidebarId: 'docsSidebar',
-            position: 'right',
-            label: 'Developer Docs',
-          },
-          {
-            type: 'docSidebar',
-            sidebarId: 'userGuideSidebar',
-            position: 'right',
-            label: 'User guide',
-          },
           {
             to: '/graphql/',
             label: 'GraphQL Playground',
@@ -89,11 +76,6 @@ const config = {
             label: 'Releases',
             position: 'right'
           }
-          /*{
-            href: 'https://github.com/twentyhq/twenty',
-            label: 'GitHub',
-            position: 'right',
-          }*/,
         ],
       },
       algolia: {

docs/sidebars.js

@@ -13,8 +13,8 @@
 
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
-  docsSidebar: [{type: 'autogenerated', dirName: 'dev-docs'}],
-  userGuideSidebar: [{type: 'autogenerated', dirName: 'user-guide'}]
+  docsSidebar: [{type: 'autogenerated', dirName: '.'}],
+  // userGuideSidebar: [{type: 'autogenerated', dirName: 'user-guide'}]
 };
 
 module.exports = sidebars;

docs/src/css/custom.css

@@ -15,7 +15,7 @@
   --ifm-font-family-monospace: 'Roboto Mono',SFMono-Regular, Menlo, Monaco, Consolas,'Liberation Mono', 'Courier New', monospace;
   --ifm-font-size-base: 14px;
   --ifm-base-spacing: 14px;
-  --ifm-line-height-base: var(--twenty-body-regular-line-height);
+  --ifm-line-height-base: 145%;
   --ifm-font-weight-base: var(--twenty-body-regular-font-weight);
   --ifm-color-primary: #11181c;
   --ifm-code-font-size: 95%;
@@ -25,7 +25,7 @@
   --ifm-toc-padding-vertical: 0.5rem;
   --ifm-breadcrumb-border-radius: 8px;
   --ifm-navbar-link-color: #687076;
-
+  --ifm-link-decoration: underline;
 
   --ifm-heading-font-weight: 600;
 
@@ -74,17 +74,29 @@ html {
 }
 
 .DocSearch-Button {
+  height: 32px !important;
   border-radius: 8px !important;
 }
 
-.navbar__items--right svg > path {
-  fill: #687076 !important;
-}
-
 .DocSearch-Button-Placeholder {
   padding: 0 100px 0 6px !important;
 }
 
+.DocSearch-Button .DocSearch-Search-Icon {
+  color: inherit !important;
+  width: 13px;
+}
+
+.DocSearch-Button-Key {
+  height: 14px !important;
+  width: 14px !important;
+  font-size: 9px !important;
+}
+
+.DocSearch-Button-Keys {
+  min-width: inherit !important;
+}
+
 .theme-edit-this-page {
   font-size: 70%;
 }
@@ -104,6 +116,10 @@ li.coming-soon a {
   cursor: default;
 }
 
+a.menu__link, a.navbar__item {
+  text-decoration: none;
+}
+
 li.coming-soon a::after {
   float: right;
   content: "soon";
@@ -120,8 +136,23 @@ li.coming-soon a::after {
 
 .menu__list-item-collapsible > a {
   text-transform: uppercase;
+  font-size:11px;
+  color: #B3B3B3;
 }
 
+.menu__list-item-collapsible > a:hover {
+  color: #B3B3B3;
+}
+
+.menu__list-item-collapsible > a {
+  text-transform: uppercase;
+  font-size:12px;
+}
+.menu__list-item-collapsible:hover {
+  background: inherit;
+}
+
+
 .theme-doc-sidebar-item-category {
   padding-top: 1.5rem;
 }
@@ -139,4 +170,16 @@ li.coming-soon a::after {
 
 .fullHeightPlayground {
   height: calc(100vh - var(--ifm-navbar-height));
+}
+
+.display-none {
+  display: none;
+}
+
+.table-of-contents__link {
+  text-decoration: none;
+}
+
+a.table-of-contents__link:hover{
+  text-decoration: underline;
 }

docs/src/theme/DocSidebarItem/Link/index.js

@@ -6,7 +6,7 @@ import Link from '@docusaurus/Link';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 import IconExternalLink from '@theme/Icon/ExternalLink';
 import styles from './styles.module.css';
-import { TbFaceIdError, TbTerminal2, TbCloud, TbServer, TbBolt, TbApps, TbTopologyStar, TbChartDots, TbBug } from "react-icons/tb";
+import { TbFaceIdError, TbTerminal2, TbCloud, TbServer, TbBolt, TbApps, TbTopologyStar, TbChartDots, TbBug, TbVocabulary } from "react-icons/tb";
 
 
 export default function DocSidebarItemLink({
@@ -29,6 +29,7 @@ export default function DocSidebarItemLink({
     'TbTopologyStar': TbTopologyStar,
     'TbChartDots': TbChartDots,
     'TbBug': TbBug,
+    'TbVocabulary': TbVocabulary
   };
 
   let IconComponent = customProps && customProps.icon ? icons[customProps.icon] : TbFaceIdError;

docs/src/theme/Icon/DarkMode/index.js

@@ -0,0 +1,9 @@
+import React from 'react';
+import { TbMoon } from 'react-icons/tb';
+import {useColorMode} from '@docusaurus/theme-common';
+
+
+export default function IconDarkMode(props) {
+  const { colorMode } = useColorMode().colorMode;
+  return colorMode === 'dark' ? <TbMoon /> : <></>;
+}

docs/src/theme/Icon/Home/index.js

@@ -0,0 +1,5 @@
+import React from 'react';
+import { TbHome } from 'react-icons/tb';
+export default function IconHome(props) {
+  return <TbHome size={14} />;
+}

docs/src/theme/Icon/LightMode/index.js

@@ -0,0 +1,9 @@
+import React from 'react';
+import { TbSun } from 'react-icons/tb';
+import {useColorMode} from '@docusaurus/theme-common';
+
+
+export default function IconLightMode(props) {
+  const { colorMode } = useColorMode().colorMode;
+  return colorMode === 'dark' ? <></>: <TbSun /> ;
+}