task: spectral - minor changes in readme and dev setup (#472)

Author: wtrocki

tools/spectral/README.md

@@ -1,11 +1,24 @@
-# Spectral updates
+# MongoDB API Spectral Validation
 
-If adding new rules or updating `.spectral.yaml` overall, the validations will instantly get updated across the `mongodb/openapi` repository.
+A set of custom validator rules for the MongoDB Atlas Programmatic API, adhering to API Standards (IPA)
+## Structure
 
-Please perform the following steps:
+- **/ipa** - Contains custom Spectral rulesets covering MongoDB API standards.
+- **/.spectral.yaml** - Contains validators not specifically related to API standards.
 
-1. Open a `mongodb/openapi` PR with the changes to `tools/spectral/.spectral.yaml`
-2. Validate that the new Spectral lint checks pass
-3. Review and merge the PR
+### Custom Rules
 
-**Note:** For MongoDB engineers, please review http://go/openapi-spectral-updates.
+For a complete list of implemented rules, please refer to the [Ruleset Documentation](./ipa/rulesets/README.md).
+
+### Updating the .spectral.yaml Ruleset
+
+When adding new rules or updating the `.spectral.yaml` file, the validations will automatically update across the `mongodb/openapi` repository. Follow these steps:
+
+1. Open a pull request (PR) in the `mongodb/openapi` repository with changes to `tools/spectral/.spectral.yaml`.
+2. Ensure that the new Spectral lint checks pass.
+3. Review and merge the PR.
+
+### Internal Documentation
+
+- Refer to the [IPA Standards](http://go/ipa) for specific rules.
+- Visit the [Spectral Wiki](http://go/openapi-spectral-updates) for additional information.