Documentation moved out of the official Terraform Registry

[stigok]

All other major provider documentation is to be found in the official Terraform Registry website. The layout and navigation is universally the same between providers, making it very easy for developers to find documentation for the relevant Terraform functionality a provider provides.

Talking from a provider consumer perspective, I find that you having moved the documentation out of the official Terraform Registry and into your own domain is cumbersome and adding complexity when using this provider.

I don't know your rationale for moving it out, but is there a possibility you might reconsider this decision?

[lkowalsk-akamai-com]

Hi @stigok, due to handling of multiple APIs, which require more sophisticated guidelines and better/more user-friendly layout we decided to move away from Terraform Registry. One of the reasons was also the possibility to update documentation without doing a release - which is the case for Terraform Registry as the documentation files are in the codebase itself. What are the main concerns you see with using the new layout?

[stigok]

I can understand the aspect of more sophisticated guidelines, as using the Akamai APIs requires a fair bit of understanding of the system as a whole, but this could potenitally be solved using the Guides tab in the registry (see image).

One could also make the argument for that the documentation should also be versioned alongside its code. It is the documentation for the codebase you're using anyway. If there's an update to the documentation, it can be communicated through the release notes so that consumers get the added benefit of e.g. clarifying previously wrong statements in the docs.

The missing part I'm mostly hit by personally is that there is no exhaustive list of Resources and Data Sources available for me to quickly find the supported arguments and attributes of specific resources I might be using.

Please excuse my one-sidedness of this argument.

[ericrichtert]

Hi @stigok, due to handling of multiple APIs, which require more sophisticated guidelines and better/more user-friendly layout we decided to move away from Terraform Registry. One of the reasons was also the possibility to update documentation without doing a release - which is the case for Terraform Registry as the documentation files are in the codebase itself. What are the main concerns you see with using the new layout?

@lkowalsk-akamai-com Here are my reasons to return to the terraform registry:

• Almost every terraform provider is documented at the terraform registry. Many tools are depended on that. For example vscode extensions. Thats works great for all providers, except akamai
• Searching in google to "akamai_dns_record" does show (the old version of) the documentation on the terraform registry. The 5th hit is the current version at the akamai techdocs. Pretty hard
• The terraform registry shows the resource/datasource name in the menu, the akamai techdocs site shows a "user (un)friendly" name. If I want to read something about "akamai_cps_dv_enrollment", why do I have to guess in the menu until I open "DV enrollment"?
• Release more often, with small bugfixes, just like the AWS provider for example. In that case, you can deploy the docs as well

[lkowalsk-akamai-com]

@ericrichtert can you please provide some more details about this concern: "Almost every terraform provider is documented at the terraform registry. Many tools are depended on that. For example vscode extensions. Thats works great for all providers, except akamai". What extensions you are referring to and how it works with other providers that does not work with Akamai?

[lkowalsk-akamai-com]

We are not planning to move the documentation back to Terraform Registry at this point. We will work on maitaining and making even more developer frieldy the documenation hosted on techdocs.akami.com

[stigok]

Is it feasible for you to add the exhaustive list of available resources to the official Terraform registry, like you had for the 3.0.0 release, but that instead of listing all the resource details, provides a link to the related TechDocs page instead?

I still find it hard to go about consuming this provider without a simple exhaustive list of available resources and data sources.