Add readme and update package.json

docs/docs-next/README.md

@@ -1,32 +1,66 @@
-# Website
+# Dagster Docs - Beta
 
-This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+This is the home of the new Dagster documentation. It is currently in beta and incomplete.
+The documentation site is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
 ### Installation
 
+The site uses [pnpm](https://pnpm.io/) for package management. 
+It also uses [vale](https://vale.sh/) to check for issues in the documentation.
+
+Install dependencies with:
+
 ```bash
-brew install pnpm
+brew install pnpm vale
 pnpm install
 ```
 
+### Overview of the docs
+
+Code in `./src` contains custom components, styles, themes, and layouts.
+Code `./content-templates` contains the templates for the documentation pages.
+Code in `./docs/` is the source of truth for the documentation.
+
+`./docs/code_examples` contains all code examples for the documentation. 
+
+The docs are broken down into the following sections:
+- [Tutorials](./docs/tutorials/)
+- [Guides](./docs/guides/)
+- [Concepts](./docs/concepts/)
+
+`sidebar.ts` and `docusaurus.config.ts` are the main configuration files for the documentation.
+
 ### Local Development
 
+To start the local development server:
+
 ```bash
 pnpm start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. Access the website at [http://localhost:3050](http://localhost:3050).
 
-### Build
+
+To lint the documentation for issues:
 
 ```bash
-pnpm build
+pnpm lint
+```
+
+To autofix linting issues and format with prettier:
+
+```bash
+pnpm lint:fix
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-### Deployment
+
+### Build
+
+To build the site for production:
 
 ```bash
-pnpm deploy
+pnpm build
 ```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.

docs/docs-next/package.json

@@ -12,10 +12,11 @@
     "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
-    "typecheck": "tsc",
+    "lint:ts": "tsc --noEmit",
+    "lint:vale": "vale ./docs --ext=.md,.mdx",
     "lint:eslint": "eslint . --ext=.tsx,.ts,.js,.md,.mdx",
-    "lint": "npx tsc --noEmit && prettier . --check && npm run lint:eslint",
-    "lint:fix": "prettier . --write && npm run lint:eslint --fix"
+    "lint": "prettier . --check && pnpm run lint:tsc && pnpm run lint:eslint && pnpm run lint:vale",
+    "lint:fix": "prettier . --write && pnpm run lint:eslint --fix"
   },
   "dependencies": {
     "@docusaurus/core": "3.5.2",