Why is it that almost no one uses terraform-plugin-docs? Including Hashicorp!

Terraform Providers Plugin Development
1

I really love the idea of the tfplugindocs to generate documentation for a provider but it seems none of the bigger providers are using it, even by Hashicorp.

Vault, GCP, AWS, etc. None of them use this plugin to generate documentation. My guess is due to a lack of flexibility, but then why not make the plugin more adaptable.

It’s just bizarre because it is part of Hashicorp’s getting started documentation so you would expect it to be the standard as it is a convenient way to document schemas and things like that.

To make matters even more strange, this plugin uses documentation category names that are not standard among all the providers. For example called the “Attribute Reference” “outputs”, etc.

So how are most people updating the documentation of their providers? By hand?

2

I quite like tfplugindocs. It’s a little rigid, but on the whole, I think my provider has wound up with better documentation with it than without.

There’s a neat workaround to organize the docs into categories. This overcame my main objection to using tfplugindocs.

While reading somebody else’s provider code recently I noticed they’re using both Description and MarkdownDescription struct elements when defining each attribute. I’ve only ever used MarkdownDescription… It makes me wonder if I’m missing something.

3

Hi @fernando-villalba,

Thank you for your interest in the terraform-plugin-docs tool. The tool is still relatively new to the Terraform provider ecosystem, so most of the major providers already had their own documentation standards and tooling set up. One of the main goals of the tool is to encourage provider documentation standardization across the ecosystem and we’ve included the tool in the documentation and the terraform-plugin-scaffolding-framework template for new providers as part of that goal.

The larger Terraform providers have hundreds of existing documentation for their providers that makes it difficult to onboard onto tfplugindocs. In the past 6 months, we’ve introduced a new migrate subcommand v0.17.0 and revamped the validate subcommand in v0.19.0 to help larger providers onboard onto the tool.

If you have any questions about how to use the tool, please feel free to create another discuss post or if you have any issues or feature request, please feel free to open an issue on GitHub.