Update README.md

Author: captainbrosset

README.md

@@ -1,58 +1,65 @@
-# web-features explorer
+# Web platform features explorer
 
-A website to visualize the web platform data that's maintained in the [web-platform-dx/web-features](https://github.com/web-platform-dx/web-features/) repository in interesting ways, including a monthly release note.
+The web platform features explorer website visualizes the web platform data that's maintained in the [web-platform-dx/web-features](https://github.com/web-platform-dx/web-features/) repository.
 
-The website: https://web-platform-dx.github.io/web-features-explorer/
+View the live website at https://web-platform-dx.github.io/web-features-explorer/.
 
-## Goal
+## Goals of the website
 
-* To visualize the web-features data.
-* To provide a way to explore the data in user-friendly ways, such as:
-  * By [baseline-low features](https://web-platform-dx.github.io/web-features-explorer/recent/) (newly available on the web platform).
-  * By [baseline-high features](https://web-platform-dx.github.io/web-features-explorer/baseline/) (widely available on the web platform).
-  * By [monthly release notes](https://web-platform-dx.github.io/web-features-explorer/monthly/).
-  * Or, by features that are [not yet available](https://web-platform-dx.github.io/web-features-explorer/nobaseline/) on the web platform.
-* To test various use cases that consumers of this data have.
-* To detect issues in the data.
+* To test and visualize the data that's in the web-features repo.
+* To connect the data to other relevant sources of information about web features.
+* To provide web developers with useful ways to stay up to date with the web and explore features.
 
 ## Architecture
 
 ### Data
 
-The data that the website is based on comes from the [web-features](https://www.npmjs.com/package/web-features) npm package, by using its **next** version (which always provide the data from the latest commit on the web-features repo).
+The data that the website is based on comes from the [web-features](https://www.npmjs.com/package/web-features) NPM package. The site uses the **next** version if the package, which provide the data from the latest commit on the web-features repo.
 
-In addition, the [@mdn/browser-compat-data](https://www.npmjs.com/package/browser-compat-data) npm package is used to get various other pieces of information, such as links to MDN documentation and links to bug trackers.
+In addition, the site uses the [@mdn/browser-compat-data](https://www.npmjs.com/package/browser-compat-data) NPM package to get various other pieces of information, such as links to MDN documentation and links to bug trackers.
+
+### Pages
+
+The web pages are built by using the [Eleventy static site generator](https://www.11ty.dev/).
+
+## Local development
+
+To run the website locally, clone the repository, make sure the dependencies are updated, and then build the site.
+
+### Update the dependencies
 
 To ensure you have the latest data:
 
 1. Run `npx npm-check-updates -u`
 
 1. Run `npm update web-features`
 
-### Build
+1. `npm install`
 
-The website consists of static HTML pages and uses a build script to generate those HTML pages from the data.
+### Build the site
 
-The template files, from which the static HTML pages get generated, use the [11ty](https://www.11ty.dev/) static website generator. The template files are found in the `site` directory.
+To build the site:
 
-The result of the build script is found in the `docs` directory, which is the directory that GitHub Pages uses to serve the website (see [Deployment](#deployment)).
+1. Run `npm run build` to generate the site
 
-To re-generate the website, after updating the data:
+1. Check the `docs` folder for the resulting build files.
 
-1. Run `npm install`
+The source template files used to build the site are in the `site` folder.
 
-1. Run `npm run build` to generate the site
-   
-   You can also run `npm run serve` to start a local server and watch for changes
+### Run and edit the site locally
+
+To run the website on a local development server:
 
-### Deployment
+1. Run `npm run serve`.
 
-The website is deployed to production using [GitHub Pages](https://pages.github.com/).
+1. Open a web browser and go to `http://localhost:8080`.
 
-The static HTML pages are generated on the [gh-pages branch](https://github.com/web-platform-dx/web-features-explorer/tree/gh-pages).
+1. Modify a source file, wait for the build to run automatically, and for the changes to appear in the browser.
+
+The result of the build script is found in the `docs` directory, which is the directory that GitHub Pages uses to serve the website (see [Deployment](#deployment)).
 
-### Automatic updates
+## Production environment
 
-The website is automatically updated on every push to the main branch by using a GitHub Actions script found in `.github/workflows/generate-site.yaml`.
+The website is deployed to production using [GitHub Pages](https://pages.github.com/). The static HTML pages are generated in the [gh-pages branch](https://github.com/web-platform-dx/web-features-explorer/tree/gh-pages) on a regular basis by the GitHub Actions script found in `.github/workflows/generate-site.yaml`.
 
 The dependencies are also automatically updated every day by using the GitHub Actions script in `.github/workflows/bump-deps.yaml`.