docs: update docs to state they are a work in progress

Author: jondricek

README.md

@@ -230,7 +230,7 @@ For more detailed examples, please refer to the [examples](./examples/README.md)
 
 ## Compatibility Matrix
 
-Our [Compatibility documentation](https://mitre-attack.github.io/attack-data-model/explanation/versioning-philosophy) tracks the compatibility between versions of the ATT&CK Data Model (ADM) TypeScript API (`@mitre-attack/attack-data-model`) and versions of the MITRE ATT&CK dataset (`mitre-attack/attack-stix-data`).
+Our [Compatibility documentation](https://mitre-attack.github.io/attack-data-model/principles/versioning-philosophy) tracks the compatibility between versions of the ATT&CK Data Model (ADM) TypeScript API (`@mitre-attack/attack-data-model`) and versions of the MITRE ATT&CK dataset (`mitre-attack/attack-stix-data`).
 
 ## Contributing
 

docusaurus/.gitignore

@@ -18,6 +18,3 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
-
-docs/*/*
-!docs/sdo/stix-bundle.schema.md

docusaurus/blog/known-issues.md

@@ -10,20 +10,22 @@ cd attack-data-model
 npm install
 ```
 
-💡 The repo is a multi-package workspace (core library + docusaurus site). Running npm install at the root will also bootstrap the docs workspace.
+💡 The repo is a multi-package workspace (core library + docusaurus site).
+Running `npm install` at the root will NOT install the dependencies for building the docs.
+Check out the [documentation](docs) contribution guide for more details.
 
 ## Verify TypeScript build
 
 ```bash
-npm run build          # compiles src → dist using tsup
-npm run test           # vitest smoke-test
+npm run build  # compiles src → dist using tsup
+npm run test   # vitest tests
 ```
 
 ## Handy npm scripts
 
 | Script | Purpose |
 |---|---|
-| npm run lint | Lints all src/** files |
+| npm run lint | Lints all `src/**` files |
 | npm run format | Prettier + ESLint fix |
 | npm run test | Run tests |
 

…w-to-guides/contributing/coding-style.md …saurus/docs/contributing/coding-style.mddocusaurus/docs/how-to-guides/contributing/coding-style.md renamed to docusaurus/docs/contributing/coding-style.md docusaurus/docs/how-to-guides/contributing/coding-style.md renamed to docusaurus/docs/contributing/coding-style.md

@@ -0,0 +1,41 @@
+# Documentation
+
+This covers how we generate the documentation for the ATT&CK Data Model.
+
+All of these commands are run from the `docusaurus/` directory, so be sure to run this first.
+Otherwise you may be very confused as to why these commands don't exist in the top-level `package.json`!
+
+```bash
+cd docusaurus/
+
+# don't forget to install the dependencies that are specific to building the documentation
+npm install
+```
+
+## Auto-generating schema reference files
+
+The script `generate-docs.sh` introspects **all** `*.schema.ts` files and
+emits Markdown to `docusaurus/docs/reference/schemas/*` which is git ignored.
+
+```bash
+npm run gendocs
+```
+
+## Run the documentation site locally
+
+Running one of the following commands will enable you to open the site locally at [http://localhost:3000](http://localhost:3000).
+
+```bash
+# opens your default browser automatically
+npm start
+
+# doesn't open your browser
+npm run -- --no-open
+```
+
+## Adding new how-to guides
+
+Its pretty easy to add a new guide. Basically just do the following:
+
+1. Create your Markdown file inside `docusaurus/docs/<topic>/my-guide.md`
+2. Update `sidebars.ts` to include it

…/how-to-guides/contributing/dev-setup.md docusaurus/docs/contributing/dev-setup.mddocusaurus/docs/how-to-guides/contributing/dev-setup.md renamed to docusaurus/docs/contributing/dev-setup.md docusaurus/docs/how-to-guides/contributing/dev-setup.md renamed to docusaurus/docs/contributing/dev-setup.md

@@ -0,0 +1,12 @@
+import DocCardList from '@theme/DocCardList';
+
+# Contributing
+
+**Step-by-step technical instructions for contributors**
+
+This section explains how to contribute to the ATT&CK Data Model repository.
+It complements the high-level `CONTRIBUTING.md` in the root of the repository by focusing on specific developer tasks.
+
+## Topics
+
+<DocCardList />

docusaurus/docs/contributing/docs.md

@@ -1,9 +1,11 @@
 # Running and Writing Tests
 
-The project uses **[Vitest](https://vitest.dev/)**.
+The ATT&CK Data Model uses **[Vitest](https://vitest.dev/)** for testing.
 
 ## Execute the full suite
 
+Running the tests is straightforward enough:
+
 ```bash
 npm test
 ```