[ehnto]

Maybe this is why infrastructure as code feels so obtuse to me, there isn't many opportunities to explain yourself in the code and so most of the communication is done in the docs.

Perhaps there is an opportunity for a more natural language approach to infrastructure as code, but I am not sure how far you can take that since the reality is still a lot of arbitrary delcarations.

[mellavora]

Better answer, thanks to Hume:

“It is very difficult to talk of the operations of the mind with perfect propriety and exactness; because common language has seldom made any very nice distinctions among them, but has generally call’d by the same term all such as nearly resemble each other. And as this is a source almost inevitable of obscurity and confusion in the author; so it may frequently give rise to doubts and objections in the reader, which otherwise he wou’d never have dream’d of.”

––A Treatise of Human Nature, by David Hume, pg. 76

[mellavora]

I doubt a "natural language" approach would work; the natural language for the domain has to be very precise. Just like the "natural language" for software has to be similar to either C or LISP. You are giving precise technical instructions which will be run by a machine.

"Hey, just spin up a server with enough capacity, alright?" Yes, sure. Please define capacity.

Those definitions are usually in the docs, which is why the code makes so many references to the docs.

Many infra-as-code systems allow you to add comments to the docs, which (if done well) can really help.

And infra-as-code is much superior to infra-as-let's-click-on-the-gui-until-it-works' Yes, it is hard to read (I know, I do it for a living). But at least you have a document which describes the infra!

[tempay]

I think a lot of the infrastructure-as-code motivation comes from struggling with documentation. At least it provides a unambiguous source of truth which is going to be correct. Understanding it and it’s quirks can be tedious but it’s better than port scanning and guessing hostnames to figure out what infrastructure exists.

[tuukkah]

> there isn't many opportunities to explain yourself in the code

Can't you include comments in your code?

[ehnto]

I've never seen it done in infrastructure as code files, but I probably would if I were writing it. Or I'd at least include some explanation in the readme.

[rmetzler]

I do it all the time in YAML config and HCL, especially stuff which is not obvious. That's the main benefit of YAML over JSON, to be able to communicate to human readers through comments.

Some stuff, like which CIDRs are necessary for which connection, are only obvious in the moment you write it, not 1 or 2 years later or for another person who joins your project next week.