WIP New HCL language docs

[Frassle]

Start on documentation for the new HCL runtime

[claude]

Documentation Review

I've reviewed the two new HCL documentation files. Here are my findings:

Issues Found

content/docs/iac/languages-sdks/hcl/_index.md

Line 16: Typo

• "designed to provider a" should be "designed to provide a"

configuration language designed to provide a familiar experience for users transitioning from Terraform while embracing Pulumi's programming model. It supports managing infrastructure on any cloud, including Azure, AWS, and Google Cloud.

Line 49: String value needs clarification
The source property appears to contain HTML, but the property name suggests a file path. The example should clarify this is inline content or use a more appropriate property name.

Lines 68-71: Inconsistent template naming
The bullet points use hcl suffix but the description at line 66 says "The hcl template is cloud agnostic." This is confusing - clarify whether these are separate templates or if there's a base hcl template.

Line 77: Command output language mismatch
The command converts to PCL but the text says "convert your Terraform files to HCL (.hcl files)". PCL (Pulumi Configuration Language) is the correct output format.

You can also convert existing Terraform HCL projects to Pulumi HCL using the `pulumi convert` command:

```bash
pulumi convert --from terraform --language pcl

This will convert your Terraform files to Pulumi HCL (.hcl files) that you can then use with Pulumi.

**Line 101: Lowercase proper noun**
"Terraform" should be capitalized as it's a proper noun (product name).

**Lines 94-105: Section structure**
The "Converting from Terraform" section has good content but could benefit from stronger organization. Consider adding a subheading for "Manual adjustments" if the list is important enough to stand out.

#### `content/docs/iac/languages-sdks/hcl/hcl-language-reference.md`

**Line 23: Table formatting - missing alignment**
The table uses single dash separators. While valid, the repository typically uses proper alignment. This is minor but worth noting for consistency.

**Line 26: Unclear description**
The outputs row says "Outputs specifies the [Pulumi stack outputs](/docs/concepts/stack#outputs) of the program and how they are computed from the `resources` is a value of the appropriate type for the template to use if no value is specified." This sentence is malformed/incomplete.

```suggestion
| `outputs` | Block | Outputs specifies the [Pulumi stack outputs](/docs/concepts/stack#outputs) of the program and how they are computed from the resources. |

Line 30: Link inconsistency
Links to "/docs/reference/pulumi-hcl/#config-options" but this appears to be a self-reference that may not exist yet. Verify this anchor exists or remove the reference.

Line 52: Section heading
"Type specifications" should follow the established pattern. Consider whether this needs to be a subsection or could be integrated into the config section more naturally.

Line 88: Incomplete description
The __logicalName property description mentions "Optional original Terraform name for compatibility" but doesn't explain when or why users would need this. Add context.

Line 102: Incomplete sentence
The table row for additionalSecretOutputs ends abruptly without completing the description.

| `additionalSecretOutputs` | list(string) | AdditionalSecretOutputs specifies properties that must be encrypted as secrets. |

Line 184: External link without context
The link to "https://github.com/hashicorp/hcl/blob/main/hclsyntax/spec.md" should be formatted as a proper markdown link with descriptive text, not a raw URL.

See the [HCL syntax specification](https://github.com/hashicorp/hcl/blob/main/hclsyntax/spec.md) for all supported expressions.

Line 113: Missing anchor link
"Custom Timeout" is referenced but no corresponding section defines what this structure contains. Either add the section or remove the link formatting.

Lines 187-336: Function documentation completeness
Many functions lack parameter descriptions and return value specifications. For a reference document, each function should include:

• Parameters with types
• Return type
• Example usage (at least for complex functions)

For example, join, lookup, range all accept parameters but don't document them.

General Observations

Positive aspects:

• Good overall structure and organization
• Comprehensive coverage of HCL features
• Helpful examples in the main index file
• Clear table formatting for reference material

Suggestions for improvement:

• Add more code examples throughout the reference guide
• Consider adding a "Common Patterns" section
• The function reference would benefit from consistent formatting with parameters, return types, and examples
• Consider linking to the Pulumi Registry examples that use HCL

Style Compliance

The documents generally follow the style guide with these notes:

• ✅ Headings use proper Title Case (H1) and Sentence case (H2+)
• ✅ Files will need trailing newlines (cannot verify from diff)
• ✅ Ordered lists use 1. format
• ✅ Links are properly formatted (except line 184)
• ⚠️ Some areas need clarity improvements as noted above

---

These are WIP docs so some incompleteness is expected. The structure is solid and provides a good foundation. Focus on fixing the typos and incomplete sentences first, then consider expanding the function documentation with examples and parameter details.

If you'd like me to help fix any of these issues or provide more detailed suggestions for specific sections, mention me (@claude) in the PR!