> For the complete documentation index, see [llms.txt](https://help.sdocs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.sdocs.com/sdocs/how-to-documentation-style-guide.md).

# Documentation Style Guide

Use this guide when you write Flow how-to articles for S-Docs.

Write for a mid-level **Salesforce Administrator**.

They know **Flow**, **Object Manager**, and **Page Layouts**.

They do not write **Apex**, **SOQL**, or **Visualforce**.

### Voice, tone, and mindset

Write as the admin's experienced copilot.

Use a tone that is empowering, clear, and reassuring.

Do not assume developer knowledge.

If you must use a technical term, explain it in plain language right away.

The golden rule is simple.

Never assume the reader knows a developer concept.

If you mention an **Apex-Defined Variable**, immediately reassure the reader that it requires clicks, not code.

Write in active voice.

Use imperative mood for steps.

Prefer short sentences.

Keep each paragraph to 1 or 2 sentences.

Good examples:

* Click **Save**.
* Select **Apex Action**.
* Map the `recordId` variable.

Avoid passive or distant phrasing.

### Terminology and capitalization

Use standard Salesforce terminology.

Match UI text exactly.

Use the label the admin sees first.

Add the API name in `code` when it helps with setup or mapping.

Examples:

* Use **Lead Source** for the UI label.
* Use `LeadSource` for the API name.
* Use **Record Id** for the Flow input label.
* Use `recordId` for the variable name.

Use inline `code` for:

* variable names
* API names
* field API names
* literal values
* exact text strings

Do not use `code` for normal UI labels.

Write **Done**, not `Done`.

### Title conventions

Do not start titles with **How To:**.

Lead with a strong action verb.

Focus on the business outcome, not the feature name.

Good examples:

* **Pass Screen Flow Inputs into Generated Documents**
* **Bulk Generate Documents using Scheduled Flows**
* **Refresh Generated Documents with Flow**

Avoid titles like these:

* **How To: User Input**
* **How To: Bulk Generate**

Name the action only when it helps the reader find the right guide faster.

### Standard page anatomy

Every guide should follow this exact order.

#### A. Why and when

Open with 1 or 2 sentences.

Explain exactly what the guide helps the admin do.

Explain when to use it.

Example:

> Use this guide when you want a **Screen Flow** to collect values from a user and place them directly into a generated **PDF**.

#### B. Start here if you are newer to Flow

Add a short beginner callout near the top of the page.

Place it before the prerequisites.

Use an `H3` for this section.

Link to [Getting Started: Automate Document Generation](/quick-start/document-generation/getting-started-automate-document-generation.md).

Use it when the guide assumes the reader already knows basic **Flow Builder** actions.

Keep this section short.

Example:

> New to Flow? Start with [Getting Started: Automate Document Generation](/quick-start/document-generation/getting-started-automate-document-generation.md).

#### C. Prerequisites checklist

Add a bulleted list before the tutorial.

List everything the admin needs before they start.

Include items like:

* permission sets
* required templates
* required Flow types
* required records or supporting setup

Keep this section skimmable.

Use bullets, not paragraphs.

#### D. Step-by-step tutorial

Use numbered steps with clear headings.

Each step should cover one logical action.

Examples:

1. **Step 1: Create the Variable**
2. **Step 2: Assign the Values**
3. **Step 3: Add the Action**

Tell the admin exactly what to click and where to find it.

Use exact UI labels.

Include at least one screenshot for each step.

If a step includes mappings, explain:

* which resource to map
* whether the value is required
* what happens if the value is blank

#### E. Troubleshooting and common errors

Add the top 2 or 3 issues the admin is most likely to hit.

Use expandable sections for each issue.

Put the symptom in the expandable title.

Inside the expandable, format the content as **Symptom → Cause → Fix**.

Example:

<details>

<summary><strong>Value is blank in the document</strong></summary>

* **Symptom:** The value is blank in the generated document.
* **Cause:** The template field syntax is wrong.
* **Fix:** Remove the object prefix from the merge field.

</details>

Keep the fixes Flow-safe.

If the action can fault, explain how to use a **Fault** path.

#### F. Advanced configurations and reference

Keep the main tutorial clean.

Move technical details to the bottom of the page.

Use this section for:

* links to the Developer Hub
* API names
* payload details
* input or output variable tables
* optional implementation notes

### Formatting and visual guidelines

#### Bold UI elements

Bold any UI element the admin clicks, selects, or types into.

Examples:

* Click **Done**.
* Select **Apex-Defined** from the **Data Type** dropdown.
* Enter the value in **Template Name or Id**.

#### Use visual click-paths

Use short click-paths instead of long paragraphs.

Format navigation like this:

**Setup** → **Object Manager** → **S-Docs** → **Fields & Relationships**

#### Use code blocks for exact syntax

Put merge fields, formulas, and exact text inputs in code blocks.

This makes them easier to copy.

Example:

```plaintext
{{!myCustomMergeField}}
```

#### Use screenshots deliberately

Add at least one screenshot per step.

Choose screenshots that confirm the exact UI state.

Crop tightly around the field, panel, or result that matters.

#### Use expandable sections for troubleshooting

Use expandable sections in **Troubleshooting and common errors**.

This keeps the page easier to scan.

It also keeps the main tutorial focused on the happy path.

#### Keep page chrome minimal

Do not include related pages on Flow how-to articles.

Do not show previous or next page pagination.

Do not show page metadata in the footer.

Keep the footer clean and task-focused.

### Flow-specific writing rules

**Flow** is the primary automation tool for this audience.

Write every tutorial to reduce hesitation and prevent setup mistakes.

#### Support newer Flow users early

Put the beginner Flow tutorial near the top of the page.

Use this link:

[Getting Started: Automate Document Generation](/quick-start/document-generation/getting-started-automate-document-generation.md)

Do this before the prerequisites when the guide assumes Flow basics.

Do not bury this link in related resources at the bottom.

#### Demystify Apex terms

When the admin must select an **Apex-Defined Variable** or **Apex Action**, add an admin note.

Use this pattern:

{% hint style="info" %}
**Admin Note:** Don't let the word "Apex" worry you. This class is included out of the box with S-Docs. You simply select it from the dropdown.
{% endhint %}

#### Explain context variables

When the admin needs to pass a record ID, remind them how to do it in **Flow**.

Use this pattern when it applies:

{% hint style="info" %}
**Admin Tip:** If your Flow is placed on a record page, create a **Text** variable named `recordId`. This name is case-sensitive. Then enable **Available for input**.
{% endhint %}

#### Emphasize order of operations

In **Assignment** elements, order matters.

List the assignments in the exact order the admin should configure them.

Example:

1. Set the text value.
2. Set the merge field name.
3. Add the item to the collection.

If a different order is required, say so clearly.

#### Clarify loop constraints

If the tutorial uses a **Loop**, call out Salesforce limits directly.

Warn the admin not to place document generation inside the loop unless the pattern explicitly supports it.

Use guidance like this:

{% hint style="warning" %}
Do not place **Generate Document** inside the loop. Add records to a collection first. Then generate the document outside the loop.
{% endhint %}

### Template syntax comparisons

When S-Docs syntax differs from standard Salesforce formulas, anchor the explanation to what the admin already knows.

Use a **Before / After** or **Instead of / Use this** comparison.

Example:

Instead of:

```plaintext
{{!Opportunity.textInputMergeField}}
```

Use:

```plaintext
{{!textInputMergeField}}
```

Explain why the syntax changes.

Say that Flow inputs do not use the standard object prefix.

### Copy-ready article outline

Use this outline when you draft a new guide:

{% code title="Flow how-to article outline" overflow="wrap" %}

```markdown
# [Strong action verb] [business outcome]

[One sentence that explains what the admin will accomplish.]
[One sentence that explains when to use this pattern.]

### Start here if you are newer to Flow

New to Flow? Start with [Getting Started: Automate Document Generation](/spaces/v7v0UNK83URKB2C83QVU/pages/2Anx4u0sLjeih7geTSL6).

## Prerequisites

- [Permission set or access requirement]
- [Required Flow type]
- [Required template, record, or supporting setup]

## Step-by-step tutorial

### Step 1: [Logical action]

[Short instruction.]

{% hint style="info" %}
**Admin Note:** [Reassure the reader if a developer term appears.]
{% endhint %}

[Screenshot]

### Step 2: [Logical action]

[Short instruction.]

[Screenshot]

## Troubleshooting and common errors

<details>
<summary><strong>[Symptom]</strong></summary>

- **Symptom:** [What the admin sees.]
- **Cause:** [Likely cause.]
- **Fix:** [Clear fix.]

</details>

<details>
<summary><strong>[Symptom]</strong></summary>

- **Symptom:** [What the admin sees.]
- **Cause:** [Likely cause.]
- **Fix:** [Clear fix.]

</details>

## Advanced Configurations & Reference

- [Developer Hub link]
- [API names, payload notes, or variable tables]
```

{% endcode %}

### Writer checklist

Before publishing, confirm that the article:

* uses an action-first title with no **How To:** prefix
* opens with a clear **Why and when** introduction
* includes the beginner Flow tutorial near the top when the guide assumes Flow basics
* lists prerequisites as bullets
* uses numbered steps with one logical action per step
* includes at least one screenshot per step
* bolds UI elements and click targets
* uses click-paths for navigation
* puts syntax and exact text in code blocks
* explains developer terms in admin-friendly language
* includes **Admin Note** guidance when **Apex** appears
* explains `recordId` when record context matters
* calls out assignment order when order matters
* warns about loop limits when loops are involved
* uses expandable sections in **Troubleshooting and common errors**
* formats each troubleshooting item as **Symptom → Cause → Fix**
* keeps technical reference details at the bottom
* does not include related pages
* does not show previous or next page pagination
* does not show page metadata in the footer


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.sdocs.com/sdocs/how-to-documentation-style-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.