S3 backend configuration page can be more clear

[krlinus]

Terraform Version

v1.5.x

Affected Pages

https://github.com/hashicorp/terraform/blob/main/website/docs/language/settings/backends/s3.mdx

What is the docs issue?

This page comes under "backends". The name of the file and the first headline are "S3". Fine There is a series of headlines after S3. They are at the same level. Example Configuration, S3 bucket permissions, DynamoDB table permissions By now, you have an idea the page is trying to tell you how to use the S3 backend, which is good Then comes Data Source Configuration It says the use of this is to access information from "other terraform configurations". My issue is this -- is this section really needed in this page? IMO it can come under "See also", as this is not the essence of how you use S3 backend. Or is it? To me the section is very confusing. Suddenly it is talking about some strange root module. Here the documentation loses direction, because new questions arise - why do I need information about some mysterious unknown "other terraform configuration"? What are the data items I need to implement my S3 backend? Can I please not use this "other" configuration, as I have enough on my plate already? Why is dependency on some assumed other external entity? This is too much! OTOH if there is no real dependency, then please don't have it in this place, as the same level of heading as "S3". Please Step your headings. Let me know what the relationship is between the title and content. Allow me to see if something can be skipped, and what portions exactly. Because as you go on reading, there is no point at which this Data Source Configuration seems to end. For the above reason, the page does not help

Proposal

Move Data Source Configuration to the end or to another page, if it is not essential to making the S3 backend work Use hyperlinks to the references made to other features, such as "data source", "root module", "outputs", "nested modules" etc Is "Configuration" part of "Data Source Configuration"? If not I guess this is where Data Source Configuration section ends. But having just talked about Data Source Configuration the page is now talking about Configuration. I am lost as to what configuration is it now, and what about the configuration that was set out to discuss - the s3 backend configuration?

References

No response

[crw]

Thanks for this docs feedback!

[teelrabbit]

Hey, I am interested in working on this issue. I would like to reformat the page so that there is another section for "more about configuration. Then add the data configuration section. Should I begin making changes?

[crw]

@teelrabbit Good question. Let me see if I can get someone to comment on the intentions behind the current page structure. You could start work on a PR, but I don't want you to have to throw away work if there is some reason things are as they are today.

[teelrabbit]

Hey, sounds good. I'll wait until you get some more details and then proceeded accordingly. Thanks for responding 🫡

[justinretzolk]

Hey @krlinus and @teelrabbit 👋 I'm the technical community manager for the Terraform AWS Provider, which also covers the S3 backend. I took a bit of time to review the current page structure, and have some follow-ups.

The page currently follows a pattern that matches how the other backend pages are loosely structured, with three main H2 headings:

• Example Configuration: a basic example showing how to use the backend with Terraform
• Data Source Configuration: a basic example showing how to use the backend with the terraform_remote_state data source
• Configuration Variables: documentation of all configuration arguments, and what they mean or do

Aside from the headers being titled slightly differently, and some pages (including S3) having additional sub-headings beneath these, the formatting is relatively consistent.

Given how intertwined they are, I'm not sure it would make sense to move the reference for terraform_remote_state to a separate area in the documentation, so from my perspective, the content on the page is all relevant, and should be kept.

With the information above, does anyone still feel that the document should be reworked, or could be clarified in some way?

[Yashrajput7232]

i would like to work on that issue

[crw]

Hi @Yashrajput7232, per https://github.com/hashicorp/terraform/issues/33785#issuecomment-1850797146 we are looking for feedback from the original commenters as to whether there is work to do here. Thanks for your interest.

[krlinus]

Hi @justinretzolk thanks for your response. It's been a 2-3 months since I opened this issue. In this time, I have been able to make the s3 state storage work, however, I have not used the locking feature From your comment I understand you are following a consistent pattern for all the pages because that is what you think fit As a user trying to master the product, I am not really expecting or asking for the same headings to be present in all the pages. True, it makes your work easier and I am not saying you should not make your work easier. So what can be done about this page?

Having moved on a bit and not having the benefit of being a first timer, my feelings regarding this are not the same or with the same intensity.

I suggest reviewing the content and putting in a bit more contextual glue so someone reading this is guided properly, even if they land on this page directly and not aware of what "data source configuration" in the context of this topic means, or that you have the explanation elsewhere if they care to read from the start

Currently this section starts like "To make use of the S3 remote state in another configuration" where the title says "Data source configuration". What is being referred to as "another configuration" here? In retrospect, it turns out what it really means to say is another terraform project (using configuration as slang for it). If you said so it would be way clearer, and I would know to skip that section because I am still working on the very first one