docs: clearer readme and docs intro

README.md

@@ -4,7 +4,7 @@
 
 # MapillaryJS
 
-MapillaryJS is an interactive street imagery and semantic mapping visualization platform on the web. It takes spatial, semantic, and texture data and renders it using JavaScript and WebGL. MapillaryJS can be augmented and extended with custom rendering, animation, camera controls, interactivity, and data providers.
+MapillaryJS is a client-side JavaScript library for interactive, extendable street imagery map experiences on the web. It takes spatial, semantic, and texture data and renders it using WebGL. MapillaryJS can be augmented and extended with custom rendering, animation, camera controls, interactivity, and data providers.
 
 <a href="https://www.mapillary.com">
 <img width="100%" alt="Mapillary" src="https://user-images.githubusercontent.com/2492302/117429732-9dbe1e80-af27-11eb-9531-47ae4df50c65.png">

doc/README.md

@@ -4,9 +4,9 @@ This website is built using [Docusaurus 2](https://docusaurus.io/).
 
 ## Development Workflow
 
-After cloning MapillaryJS, run `yarn install && yarn install-modules` in this directory to fetch the documentation dependencies. Then, you can run several commands:
+After cloning MapillaryJS, run `yarn install && yarn install-mjs` in this directory to fetch the documentation dependencies. Then, you can run several commands:
 
-- `yarn install-modules` builds the `mapillary-js` library and copies its distribution `src/mapillary-js` directory. This step is required for building the docs.
+- `yarn install-mjs` builds the `mapillary-js` library and copies its distribution to the `src/mapillary-js` directory. This step is required for building the docs.
 - `yarn ci` check for linting/formatting issues.
 - `yarn start-docs` starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. It omits the API and examples sections for faster iteration. It omits the API and examples sections for faster iteration.
 - `yarn build` generates static content into the `build` directory and can be served using any static contents hosting service.

doc/docs/intro/start.md

@@ -4,8 +4,19 @@ title: Introduction
 slug: /
 ---
 
+**MapillaryJS** is a client-side JavaScript library for building street imagery map experiences. You can use MapillaryJS to display street imagery maps in a web browser or client and you can augment the experience with your own data.
+
 This page is an overview of the MapillaryJS `v4.x` documentation and related resources.
 
+### Use cases
+
+Use cases for MapillaryJS include:
+
+- Navigating real world places in an interactive street imagery experience
+- Visualizing, editing, and animating 3D representations of geographic data
+- Dynamically displaying custom client-side data in an undistorted virtual 3D world
+- Adding markers and popups to street imagery maps programmatically
+
 ### Try MapillaryJS
 
 Our [guide to trying MapillaryJS](/docs/intro/try) will take you through the installation and give a first experience of using MapillaryJS by adding it to a simple HTML page.
@@ -36,13 +47,19 @@ The [examples section](/examples) gives you a deep dive into the details of usin
 
 ### What is MapillaryJS, Exactly?
 
-MapillaryJS is an interactive, extendable street imagery and semantic mapping visualization platform. But what does that actually mean? Let us go through it together.
+MapillaryJS is an interactive, extendable street imagery map component for semantic map visualization on the web. But what does that actually mean? Let us go through it together.
+
+As a start, you can think of MapillaryJS as a three-dimensional sibling to a traditional 2D map. While the traditional 2D map gives a great overview, the street imagery map gives you access to the finest details. MapillaryJS can be a used as a component in any web application, paired with a 2D map or on its own.
+
+#### Interactive
+
+MapillaryJS provides user interactivity to navigate the street imagery smoothly in a virtual, undistorted 3D world.
 
 #### Street Imagery
 
 Street imagery is simply images captured anywhere on earth at street-level, i.e roughly at eye-height. MapillaryJS provides interactivity to navigate street imagery smoothly in a virtual, undistorted 3D world.
 
-#### Semantic Mapping
+#### Semantic Map
 
 [Mapping](https://en.wikipedia.org/wiki/Cartography) is the practice of making or using maps.
 
@@ -50,9 +67,9 @@ Street imagery is simply images captured anywhere on earth at street-level, i.e
 
 MapillaryJS provides methods to visualize the underlying data used to create semantic 3D maps through its spatial rendering capabilities. This is useful for understanding the structure of semantic mapping algorithm output.
 
-#### Visualization Platform
+#### Extendable Visualization Component
 
-The aim of MapillaryJS is to provide the following characteristics:
+MapillaryJS aims to provide the following characteristics:
 
 - Core capabilities
   - A small set of capabilities that work really well.
@@ -74,7 +91,7 @@ The aim of MapillaryJS is to provide the following characteristics:
     - Render any 3D content, e.g. by using Three.js.
     - Build application specific interactivity.
 
-By providing the above characteristics, MapillaryJS can be a visualization platform in the browser for spatial and mapping developers to build upon and extend.
+With the above, you are able to create augmented experiences by extending the MapillaryJS core functionality.
 
 ### Glossary
 

doc/docs/intro/try.mdx

@@ -38,7 +38,7 @@ Once you have setup the prerequisites, you can try MapillaryJS in your own websi
 
 ## Add MapillaryJS to a Website
 
-### Using a Module Bundler
+### Using an ES6 Module Bundler
 
 Install the package.
 

doc/docusaurus.docs.config.js

@@ -10,7 +10,7 @@
 /** @type {import('@docusaurus/types').DocusaurusConfig} */
 module.exports = {
   title: 'MapillaryJS',
-  tagline: 'Interactive, extendable street imagery visualization platform',
+  tagline: 'Interactive, extendable street imagery map experiences',
   url: 'https://mapillary.github.io',
   baseUrl: '/mapillary-js/',
   onBrokenLinks: 'error',

doc/src/pages/index.js

@@ -17,13 +17,13 @@ import styles from './styles.module.css';
 
 const features = [
   {
-    title: 'Visualization Platform',
+    title: 'Visualization Component',
     imageUrl: 'img/hero/mjs.png',
     description: (
       <>
-        MapillaryJS is a street imagery and semantic mapping visualization
-        platform on the web. You can integrate MapillaryJS into your website
-        with just a few lines of code.
+        MapillaryJS client-side JavaScript library for building street imagery
+        map experiences on the web. You can use MapillaryJS as a component in
+        your web application with just a few lines of code.
       </>
     ),
   },
@@ -33,9 +33,8 @@ const features = [
     description: (
       <>
         MapillaryJS takes spatial, semantic, and texture data and renders it
-        using JavaScript and WebGL. You can interact with the undistorted
-        virtual 3D world and navigate the imagery from the street level or a
-        bird&apos;s eye view.
+        using WebGL. You can interact with the undistorted virtual 3D world and
+        navigate the imagery on the street level or from a bird&apos;s eye view.
       </>
     ),
   },
@@ -44,9 +43,9 @@ const features = [
     imageUrl: 'img/hero/dropoff.png',
     description: (
       <>
-        Use the MapillaryJS Extension API to extend and augment the MapillaryJS
+        You can use the extension APIs to customize and augment the MapillaryJS
         experience with your own data providers, semantic meshes, 3D models,
-        animation, camera controls, and interactivity.
+        animations, camera controls, and user interactivity.
       </>
     ),
   },