Where to document

The gitlab-terraform script provided by this project has quite some features and most of them are undocumented at the moment.

The documentation we have:

• some "usage" sections for gitlab-terraform in the README
• some recipes of how to use gitlab-terraform in combination with the Terraform Ci Templates at Terraform Template Recipes in the gitlab-org/gitlab repository.
• contribution docs in the CONTRIBUTING

The question for me is where to document gitlab-terraform features and how it plays together with the templates.

I think we need to consider multiple perspectives:

1. someone who wants to configure the template and doesn't need or want to know about gitlab-terraform at all
2. someone who wants to use gitlab-terraform, either in a pipeline (even via template and custom jobs) or locally
3. someone who wants to contribute to gitlab-terraform

For me it's clear that (3) goes into the CONTRIBUTING.md of this project.

(1) should mainly go into Terraform Template Recipes.

So, the remaining question is where to document (2).

We could either:

1. document it in this project in e.g. a docs/ folder and
   • 1.1. just link from the GitLab docs to these markdown files (or even generate pages)
   • 1.2. generate it into the GitLab docs (I think the GitLab charts do that, I don't know how though ...)
2. document it directly in gitlab-org/gitlab - would require two MRs for a new feature, but is easiest to start with probably - we do the same for the agent.

I think it would be good to start with (2), but eventually move to something like (1.2). Or even start with (1.2) if it's very simple.

However, I'd like to ask Technical Writing what is the proper way to go here - maybe you have other ideas, too?