Documentation Style Guide

Standard for writing Flow how-to articles for Salesforce Administrators using S-Docs.

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.

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.

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:

Value is blank in the document

• 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.

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:

{{!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

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:

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.

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:

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.

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:

Do not place Generate Document inside the loop. Add records to a collection first. Then generate the document outside the loop.

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:

{{!Opportunity.textInputMergeField}}

Use:

{{!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:

Flow how-to article outline

# [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]

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