| name | write-intro |
| description | Write the opening paragraph(s) for a documentation tab or section. Use when adding or rewriting an intro for a MethodSection (Portal, REST API, Terraform, etc.) or any article section that needs a short lead-in. |
Write a short intro that tells the reader what they are about to do or get — nothing more.
What an intro is
An intro orients the reader at the start of a tab or section. It answers in 2–3 sentences: what can I do here?
It is not:
- A table of contents ("this tab covers X, Y, and Z")
- A feature description ("gcore_cloud_subnet is a resource that...")
- A tutorial preamble ("in this guide you will learn to...")
- A list of constraints or implementation details
Those belong in the body of the section, not in the intro.
Rules
Length: 2–3 sentences. Short sentences. No padding.
Voice: Address the task directly. The reader should feel they can scroll past the intro and get to work immediately.
Do not write:
- "This tab covers..."
- "This guide will show you..."
- "In this section you will learn..."
- "The following steps will walk you through..."
- Any sentence that starts with "This" and describes the article itself
Links: Insert organically where they add value. Not every intro needs links. When links are relevant, choose from:
- Gcore Terraform provider v2 — link the provider when the reader may need setup context
- Terraform Registry — link when the reader may want the full resource reference beyond what the tab shows
- Specific resource page on the registry — link the resource name inline when naming it
- Related article — link when the reader needs a prerequisite that is covered elsewhere
- Other section in the same article — anchor link when the intro references something below
For Terraform tabs specifically:
- Link the specific resource name inline to its Terraform Registry page when you name it:
gcore_cloud_volume
- Link to the Terraform provider overview only in hub or setup articles where the reader genuinely needs setup context (create-an-instance, create-a-project, manage-cloud overview). For simple resource articles, omit it — the reader is already inside a Terraform tab and knows what they're doing.
- Never use the full phrase "Gcore Terraform provider v2" as link text — it is 4 words and reads like a label. Use 2–3 word variants:
[Terraform provider], [provider v2], [Gcore provider], or weave the link into a natural phrase.
- Do not apply the same template to every article. Each intro should read as if written specifically for that resource.
Examples
Bad — describes the article, not the reader's task
This tab covers how to create a subnet, configure DHCP and DNS settings, and manage subnet lifecycle using Terraform.
The gcore_cloud_network_subnet resource manages the full subnet lifecycle including CIDR allocation, DHCP, and gateway configuration.
In this section you will learn to provision a subnet with Terraform and understand how field changes affect existing VMs.
Good — orients the reader, one clear task
Create a subnet inside an existing network and configure its IP range, DHCP settings, and DNS servers with the Gcore Terraform provider v2. The gcore_cloud_network_subnet resource supports both IPv4 and IPv6.
Provision block storage with the gcore_cloud_volume resource — boot volumes from an OS image, blank data disks, or restored snapshots.
Add a cloud router to enable outbound internet access via SNAT and routing between subnets. The gcore_cloud_network_router resource handles gateway configuration and static route management.
Checklist before writing
- What is the ONE thing the reader does in this tab? Start there.
- Is there a key prerequisite worth naming? If yes, link it. If no, skip it.
- Are both provider v2 and registry links genuinely useful here, or only one?
- Does each sentence add information, or is it filler?
- Read the Portal or API intro for the same article — match the level of detail.
