terraform

terraform copied to clipboard

Proposal

Create an issue type template for requesting documentation changes. This would help with triage of issues since they could automatically have the documentation label associated with them and would also allow for a template that is more geared towards the information you want with a documentation request than just having people fill out the bug or feature request form and skip half the sections.

To do this, I think that it is just adding a new template (eg documentation.md) to https://github.com/hashicorp/terraform/tree/main/.github/ISSUE_TEMPLATE and copy one of the existing templates then adjust the fields accordingly.

cc @crw @laurapacilio

References

= https://github.com/hashicorp/terraform/issues/31441#issuecomment-1185765105

Thanks for this! It is on my todo list.

@joe-a-t I'm soliciting feedback on the new issue template. If you would like to provide feedback, please take a look at this rough draft and let me know what you think is missing or should be added: https://github.com/crw/terraform/issues/new?assignees=&labels=documentation%2Cnew&template=documentation_issue.yml

Awesome, thanks! I would lean towards separating out an Affected Page(s) section from the References section just to make it clearer where the reporter thinks the documentation needs to be updated. I'd also suggest putting the Affected Page(s) section either at the top of the sections that users fill out or right under the Terraform Version since that's the starting point if I'm reporting an issue to answer the "Where is this issue" before even getting into the "what is the issue".

For

The [hashicorp/terraform](https://github.com/hashicorp/terraform) issue tracker is 
reserved for bug reports relating to the core Terraform CLI application and configuration language.

I would suggest

The [hashicorp/terraform](https://github.com/hashicorp/terraform) `Documentation` issue type is 
reserved for reports relating to the documentation on [https://www.terraform.io/docs](). 
This issue type is only for the technical writers so that they can update documentation, it is not
monitored by the engineering team so if this issue is related to the actual functionality of Terraform
and you want engineering to take a look, please use the `Bug report` or `Feature request` issue 
types instead.

Also just more general feedback on the new issue type, I really like how the .md templates have <!-- ... --> content for the intro section and section descriptions so that it only shows up to the requester and results in less content that others looking at the issue have to skip or skim by.

@crw any update on this? I just opened another issue that would have benefited from the new issue type

Hi @joe-a-t, yes sorry, it got pushed on the back burner a bit, and I accidentally deleted my original work. I'm rebuilding it with feedback from the internal docs team. Now that 1.3 is out, it should be easy to get done in the next week or so.

Hey @crw, just wanted to flag that new documentation type doesn't appear to be available yet and https://github.com/hashicorp/terraform/blob/main/.github/ISSUE_TEMPLATE/documentation_issue.yml has this yaml syntax error

Strange. I'll check it out. Thanks for the report.

Fixed! Thanks again for the report here, it looks like a slight problem was introduced during the code review process that I missed at the time.

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues. If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.