wip

gouttebroze · Mar 31, 2020 · 6541ae0 · 6541ae0
1 parent 30cff60
commit 6541ae0
Show file tree

Hide file tree

Showing 29 changed files with 406 additions and 256 deletions.
diff --git a/docs/_includes/installation-guide-full.md b/docs/_includes/installation-guide-full.md
@@ -1,11 +1,12 @@
 - This assumes you've cloned the NRN repository locally (cloning it once is enough, no need to clone it multiple times, but it may be simpler to use one clone per variant if you're trying out multiple variants locally :wink:)
 - This assumes you're already authenticated to Zeit (you should, if you've followed the [quick start](./quick-start), or if you're familiar with Zeit already)
 
-1. `cp .env.build.example .env.build` - Duplicates the `.env.build.example` as `.env.build` _(`.env.build` is only used when working locally)_
+1. `cp .env.build.example .env.build` - Duplicates the `.env.build.example` as `.env.build`
+    - **Tip**: `.env.build` is only used when working locally
 1. Create an account for all required 3rd party vendors above, and fill-in missing environment variables in your `.env.build` file
-1. `nvm use` - Selects the right node.js version based on the `.nvmrc` file
+1. _(Optional)_ `nvm use` - Selects the right node.js version based on the `.nvmrc` file
+    - **Tip**: Ignore this if you're not using [NVM](https://github.com/nvm-sh/nvm), but you should!
 1. `yarn` - Installs all deps from `package.json`
 1. `yarn start` - Starts the app on [http://localhost:8888/](http://localhost:8888/)
-1. That's it! The project now works on your local computer, and should be identical to the online demo
 
-{% include installation-guide-tips.md %}
+That's it! The project now works on your local computer!
diff --git a/docs/_includes/installation-guide-quick-start.md b/docs/_includes/installation-guide-quick-start.md
@@ -1,8 +1,13 @@
 1. `git clone https://github.com/UnlyEd/next-right-now.git nrn-quick-start` - Clones the boilerplate
 1. `cd nrn-quick-start && git checkout v1-ssr` - Selects the variant
-1. `cp .env.build.example .env.build` - Duplicates the `.env.build.example` as `.env.build` _(`.env.build` is only used when working locally)_
-1. `nvm use` - Selects the right node.js version based on the `.nvmrc` file
-1. `yarn add -D now@16.7.3`, now@17+ requires to be authenticated to Zeit in order to launch the project **locally**, so you must use now@16 instead, to avoid additional setup
+1. `cp .env.build.example .env.build` - Duplicates the `.env.build.example` as `.env.build`
+    - **Tip**: `.env.build` is only used when working locally
+1. _(Optional)_ `nvm use` - Selects the right node.js version based on the `.nvmrc` file
+    - **Tip**: Ignore this if you're not using [NVM](https://github.com/nvm-sh/nvm), but you should!
 1. `yarn` - Installs all deps from `package.json`
+1. _(Optional)_ `yarn add -D now@16.7.3` - Installs an older `now` CLI that doesn't require you to have a Zeit account when working locally
+    - **Tip**: **You don't need to do that if you already have Zeit/Now configured on your computer** _(which may be the case if you're already familiar with Zeit)_
+    - **Tip**: `now@17+` requires to be authenticated to Zeit in order to launch the project **locally**, so we recommend to use `now@16` instead in order to avoid unnecessary setup
 1. `yarn start` - Starts the app on [http://localhost:8888/](http://localhost:8888/)
-1. That's it! The project now works on your local computer, and should be identical to the online demo
+
+That's it! The project now works on your local computer!
diff --git a/docs/_includes/installation-guide-tips.md b/docs/_includes/installation-guide-tips.md
@@ -1,4 +1 @@
-- **Tip**: You can start the project in **debug mode** (built-in for WebStorm only) [by running the WebStorm "Debug" configuration in debug mode](https://youtu.be/3vbkiRAT4e8)
-
-- **Tip**: Configure your IDE not to index `.next` and `.now` folders as they will eat a lot of your RAM because their files are changed very frequently!
-    - On WebStorm, right click on the folders and select `Mark directory as > Excluded`.
+- **Tip**: Using WebStorm? Check out our ["How to setup" Guide](../guides/ide/setup-webstorm)
diff --git a/docs/_includes/page-toc.md b/docs/_includes/page-toc.md
@@ -0,0 +1,7 @@
+---
+
+## Table of contents
+{: .no_toc .text-delta }
+
+- TOC
+{:toc}
diff --git a/docs/concepts/i18n.md b/docs/concepts/i18n.md
@@ -26,30 +26,36 @@ We will only mention i18n with NRN, not l10n.
 Both are very similar and can be grouped together as i18n, because l10n relies on i18n capabilities.
 
 The content displayed on NRN is translated using different ways, depending on where the translations are stored:
-- Content i18n - Dynamic content, data related (i.e: Blog title in FR + EN). It will depend on your data and how you fetch those data (API, SSG, etc.)
-- Platform i18n - Static content, platform related (i.e: Site links, any content that is static and not related to dynamic data).
+- Dynamic i18n - Content-related (i.e: Post title in FR + EN). It will depend on your data and how you fetch those data (API, SSG, etc.)
+- Static i18n - Everything that isn't related to dynamic content (i.e: Site links, any content that is static and not related to dynamic data).
 It will depend on how you fetch those data (vendor (API), i18n static files, etc.)
 
-It is possible, although very rare, to use the same system/vendor for both content and platform i18n.
+It is possible, although very rare, to use the same system/vendor for both "dynamic" and "static" i18n.
 
-For instance, one could imagine to store all its static content (platform i18n) within it's content i18n data. This design would have a few pros/cons:
+For instance, one could imagine to store all its static content within it's dynamic i18n content. This design would have a few pros/cons:
 - Content is available online (CMS/back office) and may be updated by non-IT teams
 - Content needs to be fetched for each request (SSR), but that could be mitigated by using SSG
 
-## A few words on "platform i18n"
+## A few words on "static i18n"
 
-I18n with Next.js isn't an easy topic, and our current implementation with platform content (Locize vendor) isn't optimal.
+I18n with Next.js isn't an easy topic, and our current implementation with static content (Locize vendor) isn't optimal.
 
-We believe the best way to deal with platform i18n (static content) is to use SSG.
-Basically, the process is to fetch your i18n content at build time and generate your pages once and for all.
+In short, we believe the best way to deal with static i18n is to use SSG. We currently use SSR, which is definitely sub-optimal and impacts performances and costs.
+
+### How to get it right
+
+Basically, the process could be to fetch your i18n content at build time and generate your pages once and for all.
 This avoids over-fetching your i18n provider for each end-user request, and also remove this vendor from the potential list of threats of your app.
 (even if your vendor API goes down, it won't affect your end-users because you only use its API at build time)
 
-But it can be complicated to achieve depending on your limitations, and will be impacted by how many pages you have to build, for instance.
+Such design also has various benefits and limitations. For example, you can't change static content without rebuilding your app,
+but it also increases the speed of your pages because you don't have to fetch static content anymore.
+
+It can be complicated to achieve depending on your needs and limitations, and will be impacted by how many pages you have to build, for instance.
 
-## A few words on "content i18n"
+## A few words on "dynamic i18n"
 
-**Content i18n** is a bit more easier in our opinion.
+**Dynamic i18n** is a bit more easier in our opinion.
 If you need those data dynamically, then you'll have to use your vendor API to fetch the i18n content,
 the same way you're using its API to fetch non-i18n data.
 

diff --git a/docs/concepts/variants.md b/docs/concepts/variants.md
@@ -8,18 +8,14 @@ nav_order: 1
 # Variants
 {: .no_toc }
 
-## Table of contents
-{: .no_toc .text-delta }
-
-- TOC
-{:toc}
+{% include page-toc.md %}
 
 ---
 
 ## What is a variant?
 
-A variant is a variation of the boilerplate. Each variant provides different **built-in** features.
-
+- A variant is a "variation" of the boilerplate. It's the same as a "Preset" of features that are "ready-to-use", because they're built-in within that variant.
+- Each variant provides different **built-in** features.
 - Each variant lives in the same NRN Github repository, but in a distinct **branch**.
 - Each variant has its own dedicated demo and "how to install" documentation.
 
@@ -35,8 +31,8 @@ The boilerplate was built with re-usability in mind, but also tries to solve non
 - Analytics
 - Monitoring
 - API usage (consumption)
-- Content i18n
-- Platform i18n
+- [Dynamic i18n](../reference/terminology#nrn-terms) (content)
+- [Static i18n](../reference/terminology#nrn-terms) (website)
 
 >Those are non-trivial features, and they can't always be build using open source software.
 >
@@ -45,7 +41,7 @@ The boilerplate was built with re-usability in mind, but also tries to solve non
 Variants are meant to cover as much possibilities as possible. For instance, you may want to use:
 - SSG or SSR
 - Multi-tenants or Multiple Single-Tenants or Single Tenant
-- Platform i18n with Locize vendor, or implemented using static files (no vendor), or maybe you don't need this feature at all
+- Static i18n with Locize vendor, or implemented using static files (no vendor), or maybe you don't need this feature at all
 - Sentry to monitor your app (client + server sides), but maybe you already use another different vendor and would like to stick with it
 - Analytics, but because you may use SSG only, and your needs are small then Google Analytics may be a better fit for you and avoid additional complexity
 - Etc.
@@ -66,9 +62,9 @@ It's a waste of time if everybody has to do that on their own, and it strongly l
 Here is a short list of all variants that we consider to support in the future:
 - ST (as an alternative to current MST)
 - SSG (as an alternative to current SSR)
-- Platform i18n without Locize provider (as an alternative to current Locize provider, which isn't free)
-- No platform i18n and no content i18n support either
-    (completely remove platform/content i18n support as an alternative for those who don't need related i18n complexity and prefer to keep things simpler)
+- Static i18n without Locize provider (as an alternative to current Locize provider, which isn't free)
+- No static i18n and no dynamic i18n support
+    (completely remove any i18n support as an alternative for those who don't need related i18n complexity and prefer to keep things simpler)
 
 ---
 
@@ -86,14 +82,34 @@ We do not plan on providing variants for:
 >
 > We are therefore open to add more/new tooling, but we must discuss it together first! :wink:
 
+## How do I know which variant is best for me?
+
+A variant is nothing more than a preset of features that are built-in within.
+
+So, to decide which one you need, you must compare what features are available versus what features you actually need.
+Also, some variants include non-free vendors, or vendors that only provide a limited plan. Depending on those things, you may chose one variant over another.
+
+Here is a summary of all features that are provided through variants:
+- **Manage multiple B2B single-tenants**: Do you need to deploy different sites (one per customer) through the same code base (monorepo design)? If so, we've got you covered.
+- **I18n**: Do you need to display your app in multiple languages?
+    If so, you should start with a variant that allows both ["dynamic i18n" and "static i18n"](../reference/terminology#nrn-terms).
+    - Also, depending on your needs, you may want to rely on a professional vendor to store, provide and help with i18n.
+        - For instance, our team love Locize for its [in-context editor](https://docs.locize.com/more/incontext-editor), because it really helps translators understand the context of a sentence, and our marketing/product team can make small changes without having to bother developers.
+- **Connect with external APIs**: Do you need to use external APIs? It's very much likely for any app nowadays.
+    If so, you should start with a variant that provides built-in support. Make sure to select one that fits your needs, we only provide built-in support for GraphQL at the moment.
+- **Monitoring**: Do you need to monitor what happens on your server and be warned about bugs and crashes? We bet you do.
+- **Analytics**: Do you need to track usage of your features and know how many users visited your site this month? We bet you do.
+
+- **Tip**: Check out our [**Vendors overview**](../reference/vendors)
+
 ---
 
 <div class="pagination-section">
     <span class="fs-4" markdown="1">
     [< Concepts](./){: .btn }
     </span>
     <span class="fs-4" markdown="1">
-    [Available variants](../getting-started/pick-variant){: .btn-blue }
+    [Find your variant](../getting-started/pick-variant){: .btn .btn-blue }
     </span>
     <span class="fs-4" markdown="1">
     [Environments and Stages >](./env-and-stages){: .btn .btn-purple }

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -7,13 +7,7 @@ nav_order: 90
 # Contributing
 {: .no_toc }
 
----
-
-## Table of contents
-{: .no_toc .text-delta }
-
-- TOC
-{:toc}
+{% include page-toc.md %}
 
 ---
 

diff --git a/docs/faq.md b/docs/faq.md
@@ -7,13 +7,7 @@ nav_order: 70
 # FAQ
 {: .no_toc }
 
----
-
-## Table of contents
-{: .no_toc .text-delta }
-
-- TOC
-{:toc}
+{% include page-toc.md %}
 
 ---
 

diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
@@ -11,6 +11,7 @@ has_toc: false
 This section contains everything about how to get started with NRN. Here is the order we recommend:
 
 1. [Video tutorials](./video-tutorials): Check our video tutorial to get an overview of what using NRN really looks like, from a developer point of view
+1. [Pre-requisites](./pre-requisites): Make sure all required tools are installed
 1. [Quick start](./quick-start): Quickly get started with the most simple variant and run it on your own computer under 5mn
 1. [Pick your variant](./pick-variant): **Advanced** - Find the variant that fits your needs through a comprehensive list of all possibilities _(make sure you are familiar with the basic [NRN concepts](../concepts) first!)_
 

diff --git a/docs/getting-started/pick-variant.md b/docs/getting-started/pick-variant.md
@@ -1,11 +1,11 @@
 ---
 layout: default
-title: Pick your variant
+title: Find my variant
 parent: Getting started
 nav_order: 30
 ---
 
-# Find and pick your variant
+# Find and use your variant
 {: .no_toc }
 
 <div class="code-example" markdown="1">
@@ -18,13 +18,13 @@ and help you get started to build your own project based on this variant.
 - Make sure you're up-to-date with the [terminology](../reference/terminology) being used.
 </div>
 
+{% include page-toc.md %}
+
 ---
 
-## Table of contents
-{: .no_toc .text-delta }
+## How do I know which variant is best for me?
 
-- TOC
-{:toc}
+[Check our guide](../concepts/variants#how-do-i-know-which-variant-is-best-for-me)
 
 ---
 
@@ -33,10 +33,9 @@ and help you get started to build your own project based on this variant.
 You can get metadata at `/api/status` on any demo, because all variants provide this API (even those that aren't tagged with `ssr`)
 
 **Quick reminders**:
+- The rendering mode (SSR/SSG) only affect how `pages` are served, it doesn't affect the API.
 - All `/api/*` endpoints are serverless functions, running under AWS Lambda
-- Even when the build configuration doesn't use SSR, because Next.js allows a hybrid design, it stills allows some page to be served from a server
-    - All API endpoints are obviously always served by an actual server, they're not affected by SSG configuration, for instance.
-    - When pages don't use SSR, it only affects `/pages`, not the api endpoints themselves
+- Next.js allows a hybrid design, thus allowing a per-page rendering mode (SSG or SSR)
 - The [database schema structure](../reference/demo-database-structure) is the same for all variants
 
 > We don't have examples using SSG at this time, but it is planned soon, don't hesitate to contribute!
@@ -75,8 +74,8 @@ The plan is to release simpler variants soon.
 | SSR vs SSG | **SSR** | SSR by default for all pages (through `pages/_app`), SSG not available |
 | Tenancy | **MST** (Hybrid MT/ST) | Deploys 2 tenants on different domains (ST), sharing the same DB and API endpoint (MT) |
 | GraphQL API (GraphCMS) | :heavy_check_mark: | Advanced GraphCMS support |
-| I18n content support (GraphCMS) | :heavy_check_mark: | Content from GraphCMS is localised |
-| I18n platform support (Locize) | :heavy_check_mark: | Static content for the platform is localised using Locize (menu, links, etc.) |
+| Dynamic i18n support (GraphCMS) | :heavy_check_mark: | Content from GraphCMS is localised (db records) |
+| Static i18n support (Locize) | :heavy_check_mark: | Content for the platform is localised using Locize (menu, links, etc.) |
 | Monitoring (Sentry) | :heavy_check_mark: | Errors are sent to Sentry in real-time (both frontend and backend) |
 | Analytics (Amplitude) | :heavy_check_mark: | Fine-grained analytics is processed in real-time (1mn graph latency on free plans) |
 
@@ -116,6 +115,14 @@ This will create a `nrn-variant-{{variant}}` folder in your current directory an
 
 {% include installation-guide-full.md variant=variant %}
 
+#### Advanced configuration
+
+{% include installation-guide-tips.md %}
+
+#### Want to learn more?
+
+- Make sure to check our ["How to use" guides](../guides) for any of the vendor used above!
+
 ---
 
 <div class="pagination-section">

diff --git a/docs/getting-started/pre-requisites.md b/docs/getting-started/pre-requisites.md
@@ -0,0 +1,31 @@
+---
+layout: default
+title: Pre-requisites
+parent: Getting started
+nav_order: 15
+---
+
+# Pre-requisites
+
+NRN expects the following to be already installed on your computer:
+
+- [NVM](https://github.com/nvm-sh/nvm) to manage installed Nodejs versions (allow to switch between versions)
+    - It's not really a requirement, but a good practice for any serious developer.
+    - If you don't use NVM, then please use node `v12` for the next steps. [Learn why](../guides/online-deployment/use-zeit)
+- Node.js should be installed (it's installed by NVM, so you're probably already covered)
+- [Git](https://git-scm.com/downloads) will be necessary to clone the repository on your computer.
+
+As you can see, there is no particular dependency to use NRN, all those tools are probably already installed on your computer!
+
+> NRN has only been extensively tested on **MacOS Catalina**, we expect **Unix-based OS** to behave properly, but **Windows** may behave differently (it shouldn't, but hasn't been tested).
+
+---
+
+<div class="pagination-section">
+    <span class="fs-4" markdown="1">
+    [< Video tutorials](./video-tutorials){: .btn }
+    </span>
+    <span class="fs-4" markdown="1">
+    [Quick start >](./quick-start){: .btn .btn-purple }
+    </span>
+</div>
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
@@ -11,22 +11,22 @@ This short tutorial will explain how to perform a super quick local installation
 
 This tutorial uses the [**`v1-ssr`**](../getting-started/pick-variant) variant, which is the ~~simplest~~ _only one_ available at this time.
 
-> It doesn't really matter if the selected variant fits your needs, the goal here is to give your a tour of what NRN can do for you, as quick as possible.
+> It doesn't really matter if the selected variant fits your needs, the goal here is to give your a tour of what NRN can do for you, as quickly as possible.
 
 ## Step by step installation
 
-> **Tip**: Using now@17+ is required for CI to work properly when deploying to Zeit, but we don't care about that as we just want to get started quickly.
-
 {% include installation-guide-quick-start.md variant=v1-ssr %}
 
+### Advanced configuration
+
 {% include installation-guide-tips.md %}
 
 ---
 
 <div markdown="1" style="text-align: center">
-**Recommended**:
+:books: **Recommended**: Go through the Concepts section:
 
-Go through the Concepts section
+Learn more about NRN concepts before getting your hands dirty&nbsp;:wink:
 </div>
 
 <div class="pagination-section">
@@ -41,14 +41,14 @@ Go through the Concepts section
 ---
 
 <div markdown="1" style="text-align: center">
-**For experienced developers**:
+:rocket: **For experimented developers** - _or if you're in a hurry_:
 
-Pick the Variant that best fit your needs and get started ASAP
+Pick the Variant that best fit your needs and it deploy online right now!
 </div>
 
 <div class="pagination-section" style="justify-content: center">
     <span class="fs-4" markdown="1">
-    [Pick your variant >](./pick-variant){: .btn .btn-blue }
+    [Find your variant >](./pick-variant){: .btn .btn-blue }
     </span>
 </div>
 
diff --git a/docs/getting-started/video-tutorials.md b/docs/getting-started/video-tutorials.md
@@ -33,6 +33,6 @@ Let's talk about the developer experience (DX) provided by NRN and how it helps
     [< Getting started](../){: .btn }
     </span>
     <span class="fs-4" markdown="1">
-    [Quick start >](./quick-start){: .btn .btn-purple }
+    [Pre-requisites >](./pre-requisites){: .btn .btn-purple }
     </span>
 </div>