More editing

Signed-off-by: Ian Maddaus <[email protected]>

Author: IanMadd

content/recipes_yaml.md

@@ -17,24 +17,6 @@ YAML recipes simplify defining Chef resources for basic use cases. While they ha
 
 For most production environments, use a hybrid approach: YAML recipes for simple static configurations and Ruby recipes for complex logic. This approach balances simplicity and functionality.
 
-## Use cases
-
-Use YAML recipes for:
-
-- Simple, static configurations
-- Declarative resource management
-- Teams preferring YAML over Ruby
-- Basic infrastructure as code
-
-Avoid YAML recipes when you need:
-
-- Dynamic node attribute access
-- Conditional logic
-- Resource notifications
-- Complex data transformations
-- Integration with Ruby libraries
-- Advanced Chef DSL features
-
 ## Create a YAML recipe
 
 To create a YAML recipe, follow these steps:
@@ -75,32 +57,36 @@ To create a YAML recipe, follow these steps:
     In this example:
 
     - the [`package` resource]({{< relref "/resources/package/" >}}) uses the `install` action and the `version` property to install Nginx 1.18.0.
-    - the [`service` resource]({{< relref "/resources/service/" >}}) uses the `enable` and `start` actions to enable and start up Nginx.
+    - the [`service` resource]({{< relref "/resources/service/" >}}) uses the `enable` and `start` actions to enable and start Nginx.
 
 ## Examples
 
 ### Basic file management
 
+Use the [`directory` resource]({{< relref "/resources/directory">}}) to create the `/opt/app_name` directory and apply owner and group permissions to the directory. Use the [`file` resource]({{< relref "/resources/">}}) to create the `/opt/app_name/config.txt` file, add text to the file, and apply file owner and group permissions to the file.
+
 ```yaml
 ---
 resources:
   - type: "directory"
-    name: "/opt/myapp"
-    owner: "myapp"
-    group: "myapp"
+    name: "/opt/app_name"
+    owner: "app_name"
+    group: "app_name"
     mode: "0755"
     recursive: true
 
   - type: "file"
-    name: "/opt/myapp/config.txt"
+    name: "/opt/app_name/config.txt"
     content: "This is a configuration file"
-    owner: "myapp"
-    group: "myapp"
+    owner: "app_name"
+    group: "app_name"
     mode: "0644"
 ```
 
 ### Package and service management
 
+Use the [`package` resource]({{< relref "/resources/package">}}) to install Nginx and curl. Then use the [`service` resource]({{< relref "/resources/service">}}) to enable and start Nginx.
+
 ```yaml
 ---
 resources:
@@ -119,6 +105,8 @@ resources:
 
 ### User management
 
+Use the [`group` resource]({{< relref "/resources/group">}}) to create a group called "developers" and the [`user` resource]({{< relref "/resources/">}}) to create a user, give them properties, and assign them to the developers group.
+
 ```yaml
 ---
 resources:
@@ -137,16 +125,39 @@ resources:
 
 ### Template with static variables
 
+Use the [`template` resource]({{< relref "/resources/template">}}) create the `/etc/app_name/config.yml` file using the `config.yml.erb` template.
+
 ```yaml
 ---
 resources:
   - type: "template"
-    name: "/etc/myapp/config.yml"
+    name: "/etc/app_name/config.yml"
     source: "config.yml.erb"
     owner: "root"
     group: "root"
     mode: "0644"
-    # Note: Variables must be static, can't use node attributes
+```
+
+### Guards
+
+Some common resource functionality is also supported, as long as the value of a property can be expressed as one of the four primitive types (string, integer, boolean, array). That means it's possible to use [`only_if` or `not_if` guards]({{< relref "/resource_common#guards" >}}) as long as they shell out to Bash or PowerShell and aren't passed a Ruby block.
+
+For example, this is supported:
+
+```yaml
+resources:
+- type: "directory"
+  name: "/var/www/html"
+  only_if: "which apache2"
+```
+
+Ruby blocks aren't supported:
+
+```yaml
+resources:
+- type: "directory"
+  name: "/var/www/html"
+  only_if: "{ ::File.exist?('/usr/sbin/apache2') }"
 ```
 
 ## Convert a YAML recipe to Ruby
@@ -217,7 +228,7 @@ resources:
     # Cannot do: notifies :restart, "service[nginx]", :delayed
 ```
 
-### No include/require functionality
+### No include or require functionality
 
 YAML recipes can't include other recipes or libraries:
 
@@ -259,7 +270,7 @@ ArgumentError: YAML recipe 'recipes/default.yml' contains multiple documents, on
 
 ### Ambiguous file extensions
 
-Chef Infra Client returns this error if multiple recipes have the same filename but a different file extension. For example, `default.yaml` and `default.yml`.
+Chef Infra Client returns this error if two recipes have the same filename with different file extensions. For example, `default.yaml` and `default.yml`.
 
 ```text
 Chef::Exceptions::AmbiguousYAMLFile: Found both default.yml and default.yaml in cookbook, update the cookbook to remove one

tools/vale/Microsoft/HeadingAcronyms.yml

@@ -5,3 +5,8 @@ level: warning
 scope: heading
 tokens:
   - '[A-Z]{2,4}'
+exceptions:
+  - API
+  - YAML
+  - TOML
+  - JSON

tools/vale/Microsoft/Headings.yml

@@ -14,15 +14,18 @@ exceptions:
   - Docker
   - Emmet
   - I
+  - JSON
   - Kubernetes
   - Linux
   - macOS
   - Marketplace
   - MongoDB
   - REPL
+  - Ruby
   - Studio
   - TypeScript
   - URLs
   - Visual
   - VS
   - Windows
+  - YAML