Documentation of Provision Module Terraform Jobs

The following discussion from !44 (merged) should be addressed:

• @ghickey started a discussion: (+1 comment)

  Another thought for the documentation of the complex data structures (or even where the data structure is not complex but a lot of gymnastics are done to produce the result) is to provide the structure information in comments where the input or output variable is declared.

The need for documentation is a recurring theme in the terraform reviews.

See also:

I would like to start seeing the inputs and outputs published for each module. There is a bunch of complex data structures being moved between the modules and it takes time to understand what is being moved back and forth (along with the possibility of errors being introduced if the data structure is misinterpreted).

Unfortunately, terraform-docs has not and probably will not be updated for v0.12 syntax and I am not aware of another documentation tool out there. It would produce tables of inputs and outputs similar to https://gitlab.com/ghickey/tf-gl-meta.

The way I would handle the complex data structures in this format is to give them a name and then provide samples or structure information in sections below their respective tables. This would be better than trying to shoehorn the data structure information into a column of the table.

I know it will not make it into this iteration, but it does need to get prioritized so that reviews are easier and persons not intimately knowledgeable of the code base can more easily contribute.

Terraform v12 lost some automated documentation tooling. This is a spike to discuss how we want to document our modules in such a way that we're not forced to update code and documentation in overly verbose and duplicate ways.