chore: add README to docusaurus-theme and website packages

packages/docusaurus-theme/README.md

@@ -0,0 +1,42 @@
+# EUI Docusaurus theme
+
+`@elastic/eui-docusaurus-theme`
+
+EUI theme for [Docusaurus](https://docusaurus.io/) made for the new EUI [documentation website](https://eui.elastic.co).
+
+## Installation and usage
+
+This package is not yet published to npm.
+
+## Local development
+
+### Prerequisites
+
+This package requires Node.js (check current version in [.nvmrc](/.nvmrc)) to be installed
+and [corepack](https://nodejs.org/api/corepack.html) to be enabled.
+
+### Installing dependencies
+
+Please run `yarn` to install dependencies:
+
+```shell
+yarn
+```
+
+### Building the package
+
+```shell
+yarn build
+```
+
+### Building in watch mode
+
+Run the following command to build this package whenever a file is edited:
+
+```shell
+yarn start
+```
+
+Please note that this package is configured to do incremental builds and sometimes `tsc` may not update
+the `lib` directory with your latest changes if you rename or delete files.
+If that's the case please run `yarn build`.

packages/website/README.md

@@ -1,41 +1,57 @@
-# Website
+# EUI documentation website
 
-This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+This package contains sources of the upcoming new EUI documentation website
+built with [Docusaurus](https://docusaurus.io/), an open-source documentation
+platform powered by React.
 
-### Installation
+This is a **private** package and is not meant to be published to npm.
+If you're looking for EUI components or utilities, check out our other [packages](../).
 
-```
-$ yarn
-```
+## Local development
 
-### Local Development
+### Prerequisites
 
-```
-$ yarn start
+Like other packages in this repository, this package requires Node.js (check version in [.nvmrc](/.nvmrc)) 
+to be installed and [corepack](https://nodejs.org/api/corepack.html) enabled.
+
+### Installing dependencies
+
+Please run `yarn` to install dependencies:
+
+```shell
+yarn
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+### Building helper packages
 
-### Build
+Before you run scripts, it's mandatory to build all local dependency packages:
 
+```shell
+yarn workspaces foreach -Rpt --from @elastic/eui-website run build
 ```
-$ yarn build
+
+### Running the development server
+
+Run a local development server with hot reloading capabilities:
+
+```shell
+yarn start
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+Please note that this command does not watch for changes in other packages' sources
+(e.g., the [theme](../docusaurus-theme) package). Please check out each package's
+README to see if watch mode is available and how to use it.
 
-### Deployment
+### Building the website
 
-Using SSH:
+This step is usually unnecessary to run locally unless you're testing production builds.
 
-```
-$ USE_SSH=true yarn deploy
+```shell
+yarn build
 ```
 
-Not using SSH:
+### Running type checks
 
+```shell
+yarn typecheck
 ```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.