cloudposse / terraform-example-module

Example Terraform Module Scaffolding
https://cloudposse.com/accelerate
Apache License 2.0
138 stars 66 forks source link

Input Variable Separation in the READMEs #32

Open philomory opened 1 year ago

philomory commented 1 year ago

Describe the Feature

First of all, apologies if this is not the correct repository in which to file this issue.

It'd be really nice if, in the READMEs of module repositories based on this template, the input variables that were actually from the module itself were documented in a separate table from the input variables related to Cloudposse's generalized system for generating resource names (e.g. involving terraform-label-null). Wading through a sea of generally-irrelevant properties like context, additional_tag_map, id_length_limit, label_key_case, etc., to find the properties you actually care about (which will vary by module but include things like s3_bucket_name on the aws-transfer-sftp module) is pretty frustrating.

Expected Behavior

It should be easy to find the properties you actually care about when configuring your infrastructure.

Use Case

I want to use Cloudposse's high-quality Terraform modules.

Describe Ideal Solution

A clean, easy to read table of input variables for each module that only shows the variables that actually impact the properties of the resources that the module provisions, with a separate table to document the input variables used to fine-tune minutiae of auto-generated resource names. Ideally, the template provided by this repository (and the associated build tooling in other repositories like build-harness) could have a straight-up list of properties to sequester in their own table. Alternatively, these properties could be flagged using some marker text in their descriptions, which the tooling could act on.

Alternatives Considered

I often just write my own ad-hoc modules rather than using Cloudposse modules. Which is stupid, they're useful, high-quality modules. But they're just so unpleasant to acquaint yourself with.

Additional Context

Below is a screenshot from the "Inputs" section of the readme from the cloudposse/terraform-aws-transfer-sftp repository. I've marked in green those inputs that concern actual, functional details of the infrastructure being provisioned, marked in red those inputs that concern Cloudposse's general scheme for constructing resource names and tags, and marked in blue those inputs that don't cleanly fall into either other group (e.g. the enabled input). image

osterman commented 1 year ago

@philomory yes, we agree - we plan to overall our usage of terraform-docs to keep the context variables in a separate chapter.