hashicorp
Reorder paragraphs for indented heredocs
Terraform Version
NA
Affected Pages
What is the docs issue?
You wrote about here doc, then about something else, then again about heredoc.
Proposal
Write paragraphs about heredoc together
References
No response
Looking at this due to the above PR. I think the point of the text in this location is to be an addendum to the overview on Heredoc syntax. So, the flow of the document is:
Heredoc Syntax (topic)
- Summary / Overview
- Warning (when to use json/yaml functions)
- Rest of usage
What do you think?
Indeed, the intention here is to try to provide the following information:
- Overview of what a heredoc template is and what it's useful for.
- What a heredoc template should not be used for.
- Various other details about specific features of heredoc templates. Today, that's indentation modes and escape sequences.
I do agree that this ordering is non-ideal for a reader who doesn't intend to use a heredoc template to generate JSON or YAML, but unfortunately we've learned of enough people making that mistake -- because JSON and YAML are used as input to a large number of resource types across many providers -- that I think a prominent warning against it is warranted.
Of course that doesn't mean that there isn't a better way to make this tradeoff, but I think just reordering the sections doesn't feel right to me because I think needing to generate JSON or YAML is the more common case than wanting to generate something else using an indented heredoc. (Of course that's just a hunch based on experience helping various people write Terraform modules; I might be wrong!)
@apparentlymart Yes, agree. We can move JSON/YAML upper.
But my complain is about that Heredoc Strings and Indented Heredocs are not together. They belongs to the same topic and should be clothier to each other.
It is all part of one section, Heredoc Strings. To try to make this clearer, the section headers would be:
header: Heredoc Strings sub-header: Summary (not explicit, but implied) sub-header: Generating JSON or YAML sub-header: Indented Heredocs sub-header: Escape Sequences
header: String Templates ...etc...
"Generating JSON or YAML" is the second sub-header as a call-out or warning to users about the use of Heredoc Strings. It is not in fact the section of our docs detailing "how to generate JSON or YAML."
Does that make more sense?
Perhaps that section should be called "Warning: Avoid using Heredoc to generate JSON or YAML".
We do normally put warnings into yellow callout boxes to make them more obviously distinct from regular content. I don't remember why I didn't do that here, but I'd guess it's problem because the old website framework only supported single-paragraph callouts due to the weird way we'd implemented it with the not-very-extensible markdown parser we were using then.
The new docs platform uses mdx markup so it might be possible to write a callout box with a paragraph and a code block in it, perhaps by using the mdx "HTML-like" syntax. But I'm not very familiar with it, since I've not been doing so much doc authoring lately.
If there is some way to express it in the current system, what I'm imagining is turning this whole subsection about JSON and YAML into a yellow callout whose heading is "Warning: Don't use heredocs to generate JSON or YAML", and then the subsequent content is similar to what's currently in the plain subsection.
I was able to find more information on the MDX components and it seems like the one we'd want here is called "inline alert", which is part of the family of different alert types in the design system.
Unfortunately the reference I found has an example which suggests that the MDX-element-shaped version of this component also expects to only have a single paragraph of content, and so cannot support having a code snippet inside the alert box:
<InlineAlert
color="warning"
title="Don't use heredocs to generate JSON or YAML"
description="Paragraph of text here. Paragraph of text here. Paragraph of text here."
/>
The web team might be able to suggest a different way to get there, or might perhaps be willing to extend this component to support multi-paragraph content (I was hope to be able to write the body text as full markdown inside the InlineAlert element), but as far as I can tell it isn't currently possible to achieve my idea of swapping the section for a callout box ("alert").