From b262f59d618570f8e213330b96276579ee9c96e4 Mon Sep 17 00:00:00 2001
From: Ville Brofeldt <ville.v.brofeldt@gmail.com>
Date: Mon, 17 Jan 2022 09:37:31 +0200
Subject: [PATCH] refine docs/readme

---
 .../Contributing/creating-viz-plugins.mdx     | 43 +++++++++++--------
 .../packages/generator-superset/README.md     |  7 ++-
 2 files changed, 28 insertions(+), 22 deletions(-)

diff --git a/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx
index 1f17fee69cae..352657487eca 100644
--- a/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx
+++ b/docs/src/pages/docs/Contributing/creating-viz-plugins.mdx
@@ -10,21 +10,24 @@ version: 1
 
 Visualizations in Superset are implemented in JavaScript or TypeScript. Superset
 comes preinstalled with several visualizations types (hereafter "viz plugins") that
-can be found under the `superset-frontend/plugins` directory. Plugins are added to
+can be found under the `superset-frontend/plugins` directory. Viz plugins are added to
 the application in the `superset-frontend/src/visualizations/presets/MainPreset.js`.
 The Superset project is always happy to review proposals for new high quality viz
 plugins. However, for highly custom viz types it is recommended to maintain a fork
-of Superset, and add the custom built plugins by hand.
+of Superset, and add the custom built viz plugins by hand.
 
 ### Prerequisites
 
-In order to create a new visualization plugin, you need the following:
+In order to create a new viz plugin, you need the following:
 
 - Run MacOS or Linux (Windows is not officially supported, but may work)
-- Node 16
+- Node.js 16
 - npm 7 or 8
 
-### Creating a simple Hello World plugin
+A general familiarity with [React](https://reactjs.org/) and the npm/Node system is
+also recommended.
+
+### Creating a simple Hello World viz plugin
 
 To get started, you need the Superset Yeoman Generator. It is recommended to use the
 version of the template that ships with the version of Superset you are using. This
@@ -33,17 +36,21 @@ can be installed by doing the following:
 ```bash
 npm i -g yo
 cd superset-frontend/packages/generator-superset
+npm i
 npm link
 ```
 
-After this you can proceed to create your viz plugin. Create a new directory wherever
-you have your repos (we'll assume under `~/src/`) with the prefix
-`superset-plugin-chart` and run the Yeoman generator:
+After this you can proceed to create your viz plugin. Create a new directory for your
+viz plugin with the prefix `superset-plugin-chart` and run the Yeoman generator:
+
+```bash
+mkdir /tmp/superset-plugin-chart-hello-world
+cd /tmp/superset-plugin-chart-hello-world
+```
+
+Initialize the viz plugin:
 
 ```bash
-cd ~/src
-mkdir superset-plugin-chart-hello-world
-cd superset-plugin-chart-hello-world
 yo @superset-ui/superset
 ```
 
@@ -86,14 +93,14 @@ $ yo @superset-ui/superset
    create src/images/thumbnail.png
 ```
 
-To build the plugin, run the following commands:
+To build the viz plugin, run the following commands:
 
 ```
 npm i --force
 npm run build
 ```
 
-Alternatively, to run the plugin in development mode (=rebuilding whenever changes
+Alternatively, to run the viz plugin in development mode (=rebuilding whenever changes
 are made), start the dev server with the following command:
 
 ```
@@ -101,11 +108,10 @@ npm run dev
 ```
 
 To add the package to Superset, go to the `superset-frontend` subdirectory in your
-Superset source folder (assuming both the `superset-plugin-chart-hello-world` plugin
-and `superset` repos are in the same root directory) and run
+Superset source folder run
 
 ```bash
-npm i -S ../../superset-plugin-chart-hello-world
+npm i -S /tmp/superset-plugin-chart-hello-world
 ```
 
 If you publish your package to npm, you can naturally install directly from there, too.
@@ -116,14 +122,15 @@ and make the following changes:
 import { SupersetPluginChartHelloWorld } from 'superset-plugin-chart-hello-world';
 ```
 
-to import the plugin and later add the following to the array that's passed to the
+to import the viz plugin and later add the following to the array that's passed to the
 `plugins` property:
 
 ```js
 new SupersetPluginChartHelloWorld().configure({ key: 'ext-hello-world' }),
 ```
 
-After that the plugin should show up when you run Superset, e.g. the development server:
+After that the viz plugin should show up when you run Superset, e.g. the development
+server:
 
 ```bash
 npm run dev-server
diff --git a/superset-frontend/packages/generator-superset/README.md b/superset-frontend/packages/generator-superset/README.md
index 0f6ad54ef504..3c90c818740d 100644
--- a/superset-frontend/packages/generator-superset/README.md
+++ b/superset-frontend/packages/generator-superset/README.md
@@ -36,12 +36,11 @@ npm install -g @superset-ui/generator-superset
 
 ## Usage
 
-Generate a new package or visualization plugin in `@superset-ui`
+Generate a new package or visualization plugin:
 
 ```bash
-cd superset-ui/packages
-mkdir superset-ui-new-package
-cd superset-ui-new-package
+mkdir /tmp/superset-plugin-chart-hello-world
+cd /tmp/superset-plugin-chart-hello-world
 yo @superset-ui/superset
 ```