📝(website) fix and improve website documentation

The website was not building anymore following our refactoring of the documentation to include cookiecutter instructions. There seem to be a bug on docusaurus versioning that prevents us from renaming an existing page... so I fixed it by renaming it also in the history. This does not impact what users see and the old versions of the website are still available. I also improved the documentation to make it clearer. In particular I repeated part of the README in the first page of the documentation to introduce the project a minimum.
openfun · Apr 15, 2022 · fcae125 · fcae125
1 parent 9c15478
commit fcae125
Show file tree

Hide file tree

Showing 21 changed files with 95 additions and 39 deletions.
diff --git a/README.md b/README.md
@@ -26,7 +26,7 @@ Among the features that `Richie` offers out of the box:
   programs (and their inter-relations),
 - Extensible with any third-party `DjangoCMS` plugin or any third-party `Django` application.
 
-## Quick preview
+## Discover Richie
 
 If you're looking for a quick preview of `Richie`, you can take a look and have a tour of
 `Richie` on our dedicated [demo site](https://demo.richie.education).
@@ -43,7 +43,7 @@ The database is regularly flushed.
 
 ## Getting started
 
-Take a look at our [Quick start guide](https://richie.education/docs/quick-start) to get started with Richie.
+Take a look at our [documentation](https://richie.education/docs/discover) to get started with Richie.
 
 ## Contributing
 

diff --git a/docs/assets/images/demo-screenshot.jpg b/docs/assets/images/demo-screenshot.jpg
diff --git a/docs/cookiecutter.md b/docs/cookiecutter.md
@@ -1,4 +1,8 @@
-# Starting a portal project based on Richie with Cookiecutter
+---
+id: cookiecutter
+title: Start your own site
+sidebar_label: Start your own site
+---
 
 We use [Cookiecutter](https://github.com/audreyr/cookiecutter) to help you
 set up a production-ready learning portal website based on
@@ -10,13 +14,22 @@ First, you need to [install cookiecutter on your machine][1].
 
 ## Run Cookiecutter
 
-Run Cookiecutter against our [Cookiecutter template](../cookiecutter):
+Navigate to the directory in which you want to create your site factory:
+
+```bash
+$ cd /path/to/your/code/directory
+```
+
+Run Cookiecutter against our [Cookiecutter template][2]:
 
 ```bash
 $ cookiecutter gh:openfun/richie --directory cookiecutter
-> organization: foo
+  > organization: foo
 ```
 
+The `--directory` option is to indicate that our Cookiecutter template is in
+a `cookiecutter` directory inside our git repository and not at the root.
+
 You will be prompted to enter an organization name, which will determine the
 name of your repository. For example, if you choose "foo" as organization
 name, your repository will be named `foo-richie-site-factory`. It's
@@ -32,14 +45,12 @@ currently are.
 Enter the newly created project and add a new site to your site factory:
 
 ```bash
-$ cd ../foo-richie-site-factory
+$ cd foo-richie-site-factory
 $ make add-site
-> site: bar
+  > site: bar
 ```
 
-This script also uses Cookiecutter against our site template located in the
-(../cookiecutter/{{cookiecutter.organization}}-richie-site-factory/template)
-directory.
+This script also uses Cookiecutter against our [site template][3].
 
 Once your new site is created, activate it:
 
@@ -57,7 +68,7 @@ $ make bootstrap
 Once the bootstrap phase is finished, you should be able to view the site at
 [localhost:8070](http://localhost:8070).
 
-You can create a full fledge demo site by running:
+You can create a full fledge demo to test your site by running:
 
 ```bash
 $ make demo-site
@@ -66,16 +77,25 @@ $ make demo-site
 Note that the README of your newly created site factory contains detailed
 information about how to configure and run a site.
 
+Once you're happy with your site, don't forget to backup your work e.g. by
+committing it and pushing it to a new git repository.
+
 ## Update your Richie site factory
 
 If we later improve our scripts, you will be able to update your own site
 factory by replaying Cookiecutter. This will override your files in the
 project's scaffolding but, don't worry, it will respect all the sites you
-will have created in the `sites` directory.
+will have created in the `sites` directory:
+
+```
+$ cookiecutter --overwrite-if-exists gh:openfun/richie --directory=cookiecutter
+```
 
 ## Help us improve this project
 
 After starting your project, please submit an issue let us know how it went and
 what other features we should add to make it better.
 
 [1]: https://cookiecutter.readthedocs.io/en/latest/installation.html
+[2]: https://github.com/openfun/richie/tree/master/cookiecutter
+[3]: https://github.com/openfun/richie/tree/master/cookiecutter/{{cookiecutter.organization}}-richie-site-factory/template
diff --git a/docs/discover.md b/docs/discover.md
@@ -4,18 +4,52 @@ title: Discover Richie
 sidebar_label: Discover Richie
 ---
 
-If you're just looking for a quick preview of `Richie`, you can take a look and have a tour of `Richie` on our dedicated [demo site](https://demo.richie.education).
+`Learning Management Systems` (LMS) are great tools for hosting and playing interactive online
+courses and MOOCs.
 
-Login/password are `admin`/`admin`. The database is regularly flushed.
+However, if you need to build a complete website with flexible content to aggregate your courses,
+in several languages and from different sources, **you will soon need a CMS**.
 
+At "France Université Numérique", we wanted to build an OpenSource portal with `Python` and
+`Django`. That's why we built `Richie` on top of [DjangoCMS](https://www.django-cms.org), one of
+the best CMS on the market, as a toolbox to easily create full fledged websites with a catalog of
+online courses.
 
-### Start your own site
+![screenshot of richie demo site](assets/images/demo-screenshot.jpg)
+
+Among the features that `Richie` offers out of the box:
+
+- multi-lingual by default,
+- advanced access rights and moderation,
+- catalog of courses synchronized with one or more `LMS` instances,
+- search engine based on `Elasticsearch` and pre-configured to offer full-text queries,
+  multi-facetting, auto-complete,...
+- flexible custom pages for courses, organizations, categories, teachers, blog posts,
+  programs (and their inter-relations),
+- Extensible with any third-party `DjangoCMS` plugin or any third-party `Django` application.
+
+## Quick preview
+
+If you're looking for a quick preview of `Richie`, you can take a look and have a tour of
+`Richie` on our dedicated [demo site](https://demo.richie.education).
+
+It is connected back-to-back with a demo of OpenEdX running on
+[OpenEdX Docker](https://github.com/openfun/openedx-docker).
+
+Two users are available for testing:
+
+- admin: `[email protected]`/`admin`
+- student: `[email protected]`/`edx`
+
+The database is regularly flushed.
+
+## Start your own site
 
 The next step after discovering Richie on the demo is to start your own project. We provide a
 production-ready template based on [Cookiecutter](https://github.com/audreyr/cookiecutter) that
 allows you to generate your project in seconds.
 
-Follow the guide on [starting your own Richie project with Cookiecutter](./cookiecutter.md).
+Follow the guide on [starting your own Richie site with Cookiecutter](./cookiecutter.md).
 
 Once you created a new site, you will be able to fully customize it:
 

diff --git a/docs/native-installation.md b/docs/native-installation.md
@@ -8,7 +8,7 @@ This document aims to list all needed steps to have a working `Richie`
 installation on your laptop.
 
 A better approach is to use [`Docker`](https://docs.docker.com) as explained in
-our guide for [container-native](quick-start.md) instructions.
+our guide for [container-native installation](installation.md) instructions.
 
 ## Installing a fresh server
 

diff --git a/website/core/Footer.js b/website/core/Footer.js
@@ -20,7 +20,7 @@ class Footer extends React.Component {
         <section className="sitemap">
           <div>
             <h5>Documentation</h5>
-            <a href={this.docUrl('quick-start.html', this.props.language)}>Getting&nbsp;Started</a>
+            <a href={this.docUrl('discover.html', this.props.language)}>Getting&nbsp;Started</a>
             <a href="/versions">Versions</a>
             <a href={this.docUrl('contributing.html', this.props.language)}>Contributing</a>
           </div>

diff --git a/website/pages/en/help.js b/website/pages/en/help.js
@@ -28,7 +28,7 @@ module.exports = function Help(props) {
   const supportLinks = [
     {
       content: `Learn more in the [documentation](${docUrl(
-        'quick-start.html',
+        'discover.html',
       )}). Please tell us if anything is missing or out-of-date.`,
       title: 'Browse Docs',
     },

diff --git a/website/pages/en/index.js b/website/pages/en/index.js
@@ -18,7 +18,9 @@ class HomeSplash extends React.Component {
     );
 
     const ProjectTitle = () => (
-      <h2 className="projectTitle">Richie helps educators create rich online learning portals..</h2>
+      <h2 className="projectTitle">
+        Richie helps educators create rich online learning portals...
+      </h2>
     );
 
     const PromoSection = (props) => (
@@ -71,7 +73,7 @@ module.exports = class Index extends React.Component {
             content:
               '<p>Richie helps educators create online learning portals.</p>' +
               "<p>Build websites including online course catalogs in days with Richie's content management system.</p>" +
-              `<a class="button" href="${docUrl('quick-start.html')}">Get started</a>`,
+              `<a class="button" href="${docUrl('discover.html')}">Get started</a>`,
             image: `${baseUrl}img/undraw_professor.svg`,
             imageAlign: 'left',
             title: siteConfig.tagline,

diff --git a/website/pages/en/versions.js b/website/pages/en/versions.js
@@ -36,7 +36,7 @@ module.exports = function Versions(props) {
                   <a
                     href={`${siteConfig.baseUrl}${siteConfig.docsUrl}/${
                       props.language ? props.language + '/' : ''
-                    }quick-start`}
+                    }discover`}
                   >
                     Documentation
                   </a>
@@ -60,7 +60,7 @@ module.exports = function Versions(props) {
                   <a
                     href={`${siteConfig.baseUrl}${siteConfig.docsUrl}/${
                       props.language ? props.language + '/' : ''
-                    }next/quick-start`}
+                    }next/discover`}
                   >
                     Documentation
                   </a>
@@ -85,7 +85,7 @@ module.exports = function Versions(props) {
                         <a
                           href={`${siteConfig.baseUrl}${siteConfig.docsUrl}/${
                             props.language ? props.language + '/' : ''
-                          }${version}/quick-start`}
+                          }${version}/discover`}
                         >
                           Documentation
                         </a>

diff --git a/website/siteConfig.js b/website/siteConfig.js
@@ -31,7 +31,7 @@ module.exports = {
   headerLinks: [
     { href: '/', label: 'Home' },
     { href: repoUrl, label: 'GitHub' },
-    { doc: 'quick-start', label: 'Documentation' },
+    { doc: 'discover', label: 'Documentation' },
     { page: 'help', label: 'Help' },
   ],
 

diff --git a/website/versioned_docs/version-1.12/native-installation.md b/website/versioned_docs/version-1.12/native-installation.md
@@ -9,7 +9,7 @@ This document aims to list all needed steps to have a working `Richie`
 installation on your laptop.
 
 A better approach is to use [`Docker`](https://docs.docker.com) as explained in
-our guide for [container-native](quick-start.md) instructions.
+our guide for [container-native](installation.md) instructions.
 
 ## Installing a fresh server
 

diff --git a/website/versioned_docs/version-1.12/quick-start.md b/website/versioned_docs/version-1.12/quick-start.md
@@ -1,8 +1,8 @@
 ---
-id: version-1.12-quick-start
+id: version-1.12-discover
 title: Getting started with Richie
 sidebar_label: Quick start
-original_id: quick-start
+original_id: discover
 ---
 
 If you're just looking for a quick preview of `Richie`, you can take a look and have a tour of `Richie` on our dedicated [demo site](https://demo.richie.education).

diff --git a/website/versioned_docs/version-2.0.0/native-installation.md b/website/versioned_docs/version-2.0.0/native-installation.md
@@ -9,7 +9,7 @@ This document aims to list all needed steps to have a working `Richie`
 installation on your laptop.
 
 A better approach is to use [`Docker`](https://docs.docker.com) as explained in
-our guide for [container-native](quick-start.md) instructions.
+our guide for [container-native](discover.md) instructions.
 
 ## Installing a fresh server
 

diff --git a/website/versioned_docs/version-2.0.0/quick-start.md b/website/versioned_docs/version-2.0.0/quick-start.md
@@ -1,8 +1,8 @@
 ---
-id: version-2.0.0-quick-start
+id: version-2.0.0-discover
 title: Getting started with Richie
 sidebar_label: Quick start
-original_id: quick-start
+original_id: discover
 ---
 
 If you're just looking for a quick preview of `Richie`, you can take a look and have a tour of `Richie` on our dedicated [demo site](https://demo.richie.education).

diff --git a/website/versioned_docs/version-2.8.0/quick-start.md b/website/versioned_docs/version-2.8.0/quick-start.md
@@ -1,8 +1,8 @@
 ---
-id: version-2.8.0-quick-start
+id: version-2.8.0-discover
 title: Getting started with Richie
 sidebar_label: Quick start
-original_id: quick-start
+original_id: discover
 ---
 
 If you're looking for a quick preview of `Richie`, you can take a look and have a tour of `Richie` on our dedicated [demo site](https://demo.richie.education).

diff --git a/website/versioned_sidebars/version-1.12-sidebars.json b/website/versioned_sidebars/version-1.12-sidebars.json
@@ -1,7 +1,7 @@
 {
   "version-1.12-docs": {
     "Getting started": [
-      "version-1.12-quick-start",
+      "version-1.12-discover",
       "version-1.12-docker-development",
       "version-1.12-native-installation"
     ],

diff --git a/website/versioned_sidebars/version-1.13-sidebars.json b/website/versioned_sidebars/version-1.13-sidebars.json
@@ -1,7 +1,7 @@
 {
   "version-1.13-docs": {
     "Getting started": [
-      "version-1.13-quick-start",
+      "version-1.13-discover",
       "version-1.13-docker-development",
       "version-1.13-native-installation"
     ],

diff --git a/website/versioned_sidebars/version-1.16-sidebars.json b/website/versioned_sidebars/version-1.16-sidebars.json
@@ -1,7 +1,7 @@
 {
   "version-1.16-docs": {
     "Getting started": [
-      "version-1.16-quick-start",
+      "version-1.16-discover",
       "version-1.16-docker-development",
       "version-1.16-native-installation"
     ],

diff --git a/website/versioned_sidebars/version-2.0.0-sidebars.json b/website/versioned_sidebars/version-2.0.0-sidebars.json
@@ -1,7 +1,7 @@
 {
   "version-2.0.0-docs": {
     "Getting started": [
-      "version-2.0.0-quick-start",
+      "version-2.0.0-discover",
       "version-2.0.0-docker-development",
       "version-2.0.0-native-installation"
     ],

diff --git a/website/versioned_sidebars/version-2.2.0-sidebars.json b/website/versioned_sidebars/version-2.2.0-sidebars.json
@@ -1,7 +1,7 @@
 {
   "version-2.2.0-docs": {
     "Getting started": [
-      "version-2.2.0-quick-start",
+      "version-2.2.0-discover",
       "version-2.2.0-docker-development",
       "version-2.2.0-native-installation"
     ],

diff --git a/website/versioned_sidebars/version-2.8.1-sidebars.json b/website/versioned_sidebars/version-2.8.1-sidebars.json
@@ -1,7 +1,7 @@
 {
   "version-2.8.1-docs": {
     "Getting started": [
-      "version-2.8.1-quick-start",
+      "version-2.8.1-discover",
       "version-2.8.1-docker-development",
       "version-2.8.1-native-installation"
     ],