docs: reorganize README with emphasis on end user documentation (#333)

Fixes #265
climateinteractive · Jul 24, 2023 · 064148b · 064148b
1 parent 8a3ead0
commit 064148b
Show file tree

Hide file tree

Showing 27 changed files with 834 additions and 737 deletions.
diff --git a/README.md b/README.md
diff --git a/examples/sir/README.md b/examples/sir/README.md
@@ -25,7 +25,7 @@ cd ./sir
 # Create a new project (you can also use yarn or pnpm here, if preferred).
 # Be sure to choose the "Default" template, which will make use of the
 # existing files in the `config` directory.
-npm create @sdeverywhere
+npm create @sdeverywhere@latest
 
 # Enter development mode for the sample model.  This will start a live
 # development environment that will build a WebAssembly version of the

diff --git a/examples/template-default/README.md b/examples/template-default/README.md
@@ -23,7 +23,7 @@ The project includes:
 ```sh
 # Create a new project (you can also use yarn or pnpm here, if preferred).
 # Be sure to choose the "Default" template.
-npm create @sdeverywhere
+npm create @sdeverywhere@latest
 
 # Enter development mode for your model.  This will start a live
 # development environment that will build a WebAssembly version of the

diff --git a/examples/template-minimal/README.md b/examples/template-minimal/README.md
@@ -19,7 +19,7 @@ to add the `@sdeverywhere/plugin-config` package to your project.)
 ```sh
 # Create a new project (you can also use yarn or pnpm here, if preferred).
 # Be sure to choose the "Minimal" template.
-npm create @sdeverywhere
+npm create @sdeverywhere@latest
 
 # Enter development mode for your model.  This will start a live
 # development environment that will build a WebAssembly version of the

diff --git a/notes/Code Generation Diagram.pdf b/notes/Code Generation Diagram.pdf
diff --git a/notes/Code-Generation-Diagram.png b/notes/Code-Generation-Diagram.png
diff --git a/notes/Run Loop Diagram.pdf b/notes/Run Loop Diagram.pdf
diff --git a/notes/Run-Loop-Diagram.png b/notes/Run-Loop-Diagram.png
diff --git a/notes/Using SDEverywhere to Make a Vensim Model into a Web Application.md b/notes/Using SDEverywhere to Make a Vensim Model into a Web Application.md
diff --git a/notes/Using SDEverywhere to Make a Vensim Model into a Web Application.pdf b/notes/Using SDEverywhere to Make a Vensim Model into a Web Application.pdf
diff --git a/notes/Visitor Classes Diagram.afdesign b/notes/Visitor Classes Diagram.afdesign
diff --git a/notes/Visitor Classes Diagram.pdf b/notes/Visitor Classes Diagram.pdf
diff --git a/notes/Visitor-Classes-Diagram.png b/notes/Visitor-Classes-Diagram.png
diff --git a/notes/smooth3.png b/notes/smooth3.png
diff --git a/packages/build/README.md b/packages/build/README.md
@@ -1,6 +1,30 @@
 # @sdeverywhere/build
 
-This package provides the core build and plugin API for SDEverywhere.
+This package provides the core build and plugin API for [SDEverywhere](https://github.com/climateinteractive/SDEverywhere).
+
+## Quick Start
+
+The best way to get started with SDEverywhere is to follow the [Quick Start](https://github.com/climateinteractive/SDEverywhere#quick-start) instructions.
+If you follow those instructions, the `@sdeverywhere/build` package will be added to your project automatically, in which case you can skip the following section.
+
+## Install
+
+```sh
+# npm
+npm install --save-dev @sdeverywhere/build
+
+# pnpm
+pnpm add -D @sdeverywhere/build
+
+# yarn
+yarn add -D @sdeverywhere/build
+```
+
+## Usage
+
+Most users do not need to interact with the `@sdeverywhere/build` package directly; it is primarily used in the implementation of the `sde` command line tool (from the `@sdeverywhere/cli` package).
+
+However, if you are building a custom plugin or a tool that drives the build process programmatically, you can refer to the API documentation below for more details.
 
 ## Documentation
 

diff --git a/packages/check-core/README.md b/packages/check-core/README.md
@@ -1,7 +1,33 @@
 # @sdeverywhere/check-core
 
-This package provides the core implementation of SDEverywhere's system dynamics
-model checking and comparison functionality.
+This package provides the core implementation of the System Dynamics model checking and comparison functionality in [SDEverywhere](https://github.com/climateinteractive/SDEverywhere).
+
+## Quick Start
+
+The best way to get started with SDEverywhere is to follow the [Quick Start](https://github.com/climateinteractive/SDEverywhere#quick-start) instructions.
+If you follow those instructions, the `@sdeverywhere/plugin-check` package will be added to your project, and that package uses `@sdeverywhere/check-core` as an implementation detail.
+Therefore, most users do not need to install this package directly.
+
+## Install
+
+As noted above, most users do not need to install this package directly, but for more advanced use cases, it can be installed as follows.
+
+```sh
+# npm
+npm install @sdeverywhere/check-core
+
+# pnpm
+pnpm add @sdeverywhere/check-core
+
+# yarn
+yarn add @sdeverywhere/check-core
+```
+
+## Usage
+
+Most users do not need to interact with the `@sdeverywhere/check-core` package directly; it is primarily used in the implementation of `@sdeverywhere/plugin-check` and the related UI package, `@sdeverywhere/check-ui-shell`.
+
+However, if you would like to build a custom tool for running checks and comparison tests on models, you can refer to the API documentation below for more details.
 
 ## Documentation
 

diff --git a/packages/check-ui-shell/README.md b/packages/check-ui-shell/README.md
@@ -1,11 +1,37 @@
 # @sdeverywhere/check-ui-shell
 
-This package provides a complete user interface for a model check/comparison
-report as generated by SDEverywhere.
+This package provides a complete user interface for a model check/comparison report as generated by [SDEverywhere](https://github.com/climateinteractive/SDEverywhere).
 
-Note: Most developers will not need to work with this package directly.
-It is generally used as an implementation detail by the
-`@sdeverywhere/plugin-check` package as part of generating a report.
+## Quick Start
+
+The best way to get started with SDEverywhere is to follow the [Quick Start](https://github.com/climateinteractive/SDEverywhere#quick-start) instructions.
+If you follow those instructions, the `@sdeverywhere/plugin-check` package will be added to your project, and that package uses `@sdeverywhere/check-ui-shell` as an implementation detail.
+Therefore, most users do not need to install this package directly.
+
+## Install
+
+As noted above, most users do not need to install this package directly, but for more advanced use cases, it can be installed as follows.
+
+```sh
+# npm
+npm install @sdeverywhere/check-ui-shell
+
+# pnpm
+pnpm add @sdeverywhere/check-ui-shell
+
+# yarn
+yarn add @sdeverywhere/check-ui-shell
+```
+
+## Usage
+
+Most users do not need to interact with the `@sdeverywhere/check-ui-shell` package directly; it is primarily used in the implementation of the `@sdeverywhere/plugin-check` package.
+
+However, if you would like to build a custom tool for running checks and comparison tests on models, you can refer to the API documentation below for more details.
+
+## Documentation
+
+API documentation is available in the [`docs`](./docs/index.md) directory.
 
 ## License