Link concepts to guides

gouttebroze · Mar 31, 2020 · 0c1386b · 0c1386b
1 parent 99d1523
commit 0c1386b
Show file tree

Hide file tree

Showing 10 changed files with 36 additions and 15 deletions.
diff --git a/docs/concepts/analytics.md b/docs/concepts/analytics.md
@@ -42,7 +42,7 @@ If you want fine-grained control over the data you want to collect, it's the per
 
 Also, it provides a really great react package.
 
-[Read our review](../reference/vendors).
+[Read our vendors review](../reference/vendors).
 
 ---
 
@@ -51,6 +51,9 @@ Also, it provides a really great react package.
     [< I18n](./i18n){: .btn }
     </span>
     <span class="fs-4" markdown="1">
+    [Guides: Analytics](../guides/analytics){: .btn .btn-blue }
+    </span>
+    <span class="fs-4" markdown="1">
     [Monitoring >](./monitoring){: .btn .btn-purple }
     </span>
 </div>
diff --git a/docs/concepts/ci-cd.md b/docs/concepts/ci-cd.md
@@ -53,6 +53,9 @@ Zeit uses the term "preview", which is exactly the same as what we call "staging
     [< Monitoring](./monitoring){: .btn }
     </span>
     <span class="fs-4" markdown="1">
+    [Guides: CI/CD](../guides/ci-cd){: .btn .btn-blue }
+    </span>
+    <span class="fs-4" markdown="1">
     [Testing >](./testing){: .btn .btn-purple }
     </span>
 </div>
diff --git a/docs/concepts/graphql.md b/docs/concepts/graphql.md
@@ -36,6 +36,9 @@ You can always start with it and use your own self-managed GraphQL server later
     [< Tenancy](./tenancy){: .btn }
     </span>
     <span class="fs-4" markdown="1">
+    [Guides: GraphQL API](../guides/graphql-api){: .btn .btn-blue }
+    </span>
+    <span class="fs-4" markdown="1">
     [I18n >](./i18n){: .btn .btn-purple }
     </span>
 </div>
diff --git a/docs/concepts/i18n.md b/docs/concepts/i18n.md
@@ -73,7 +73,7 @@ There is no bullet-proof-fit-them-all solution on this, it depends on your requi
     [< GraphQL](./graphql){: .btn }
     </span>
     <span class="fs-4" markdown="1">
-    [Analytics >](./analytics){: .btn .btn-blue }
+    [Guides: I18n](../guides/i18n){: .btn .btn-blue }
     </span>
     <span class="fs-4" markdown="1">
     [Analytics >](./analytics){: .btn .btn-purple }

diff --git a/docs/concepts/monitoring.md b/docs/concepts/monitoring.md
@@ -33,6 +33,9 @@ Monitoring is so important, you can't afford to get it wrong. Tools matter!
     [< Analytics](./analytics){: .btn }
     </span>
     <span class="fs-4" markdown="1">
+    [Guides: Monitoring](../guides/monitoring){: .btn .btn-blue }
+    </span>
+    <span class="fs-4" markdown="1">
     [CI/CD >](./ci-cd){: .btn .btn-purple }
     </span>
 </div>
diff --git a/docs/concepts/testing.md b/docs/concepts/testing.md
@@ -33,6 +33,9 @@ You can also run them non-interactively using `yarn e2e:run` script.
     [< CI/CD](./ci-cd){: .btn }
     </span>
     <span class="fs-4" markdown="1">
+    [Guides: Testing](../guides/testing){: .btn .btn-blue }
+    </span>
+    <span class="fs-4" markdown="1">
     [Getting started: Pick your variant >](../getting-started/pick-variant){: .btn .btn-purple }
     </span>
 </div>
diff --git a/docs/concepts/variants.md b/docs/concepts/variants.md
@@ -8,6 +8,10 @@ nav_order: 1
 # Variants
 {: .no_toc }
 
+<div class="code-example" markdown="1">
+A variant is similar to a "Preset" of features that are "ready-to-use".
+</div>
+
 {% include page-toc.md %}
 
 ---
@@ -41,7 +45,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
-- Static i18n with Locize vendor, or implemented using static files (no vendor), or maybe you don't need this feature at all
+- Static i18n using a vendor (i.e: Locize), 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.
@@ -51,15 +55,15 @@ We don't intend of supporting all possible variations, but we'll try to focus on
 
 The more variants we will offer, and the easiest it will be for any newcomer to get started quickly with a variant that really fits their needs.
 
-For instance, when creating [NRN Admin](https://github.com/UnlyEd/next-right-now-admin), we got started from the `v1-ssr` variant and had to manually remove MST and i18n because we didn't need those.
+> For instance, when creating [NRN Admin](https://github.com/UnlyEd/next-right-now-admin), we got started from the `v1-ssr` variant and had to manually remove MST and i18n because we didn't need those.
 
 It's a waste of time if everybody has to do that on their own, and it strongly limits the boilerplate re-usability.
 
 ---
 
 ## Which variants **are** being considered?
 
-Here is a short list of all variants that we consider to support in the future:
+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)
 - Static i18n without Locize provider (as an alternative to current Locize provider, which isn't free)
@@ -70,7 +74,7 @@ Here is a short list of all variants that we consider to support in the future:
 
 ## Which variants **aren't** being considered?
 
-We do not plan on providing variants for:
+We **do not plan** on providing variants for:
 - Different monitoring tool than Sentry, as it is one of the best out there, provides a generous free plan, and does the job really well.
 - Different analytics tool than Amplitude, as it is the most flexible analytics tool we've experienced.
     For instance, Google Analytics feels like some stuff invented during Stone age in comparison, and GA doesn't play well at all with CSR rendering.
@@ -100,7 +104,7 @@ Here is a summary of all features that are provided through variants:
 - **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)
+- **Tip**: Read our [**Vendors overview**](../reference/vendors)
 
 ---
 

diff --git a/docs/guides/i18n/use-locize.md b/docs/guides/i18n/use-locize.md
@@ -10,12 +10,18 @@ nav_order: 20
 
 <div class="code-example" markdown="1">
 The content displayed on NRN is translated using different ways, depending on where the translations are stored:
-- GraphCMS - Dynamic content (fetched from the DB, through GraphCMS API). This content can be updated through GraphCMS backoffice.
-- Locize - Static content (fetched from Locize API). This content can be updated through Locize backoffice, or when using in-context editor.
+- Dynamic content - GraphCMS (fetched from the DB, through GraphCMS API). This content can be updated through GraphCMS backoffice.
+- Static content - Locize (fetched from Locize API). This content can be updated through Locize backoffice, or when using in-context editor.
 </div>
 
 ## Overview
 
+## How to use Locize in-context editor?
+
+You can enable **Locize in-context editor mode**, by appending `?locize=true` to the url, see [https://nrn-customer1.now.sh/?locize=true](https://nrn-customer1.now.sh/?locize=true)
+
+Note that it's only enabled in development and staging stages, not in production.
+
 ## Fetching translations through Locize provider
 
 > When the content we want to display doesn't come from GraphCMS API, then it's considered as a "static" content.

diff --git a/docs/guides/ide/setup-webstorm.md b/docs/guides/ide/setup-webstorm.md
@@ -27,7 +27,7 @@ You can start the project in **debug mode** (built-in for WebStorm only) [by run
 
 The configuration file is built-in and should be available as soon as you open the project using WebStorm.
 
-## Configure GraphQL support
+## Configure in-editor GraphQL support
 
 Install [JS GraphQL IntelliJ Plugin](https://github.com/jimkyndemeyer/js-graphql-intellij-plugin): GraphQL language support for WebStorm, IntelliJ IDEA and other IDEs based on the IntelliJ Platform.
 

diff --git a/docs/reference/vrac.md b/docs/reference/vrac.md
@@ -3,8 +3,4 @@ layout: default
 nav_exclude: true
 ---
 
-> **Tip**: You can enable **Locize in-context editor mode** in order to localise your static content, by appending `?locize=true` to the url, see [https://nrn-customer1.now.sh/?locize=true](https://nrn-customer1.now.sh/?locize=true) _(this is only enabled in development and staging stages, not in production)_
-
-> **Tip**: You can change **which customer is started by default** by changing the [`./now.json`](./now.json) symlink (ie: `ln -s ./now.customer2.staging.json ./now.json`)
-
-> **Tip**: If there are tools that you don't need/like, read our [guide about how to remove them](README_HOW_TO_REMOVE.md).
+- **Tip**: You can change **which customer is started by default** by changing the [`./now.json`](./now.json) symlink (ie: `ln -s ./now.customer2.staging.json ./now.json`)