Boomi Technical Writing Style Guide

As a content team, we are changing how we write and communicate. We are more conversational now and adapt our writing style and conventions to reflect industry changes. Traditionally, we have broadly based our writing style and standards on the Chicago Manual of Style and the Microsoft Writing Style Guide. However, we now find the Google writing style more relatable and conversational, so we have made the required changes to how we write and communicate. We are fans of short, crisp, and conversational.

General Guidelines

• Whenever possible use a "generic" account such as "Documentation" or "Boomi Documentation" when capturing images.
• Add an image only if it's absolutely necessary. Localizing images is expensive and time-consuming.
• Take as few full-screen images as possible. They're too large for a Help page and every time something in the UI changes you'll have to recapture the full-screen image.
• Make sure the image shows only the topic at hand. Otherwise it's difficult for users to see what's being described in the Help topic.
• Do not include company-sensitive information in images such as employee names or e-mail addresses. Tip: use Snagit's blur tool (set at 75 intensity in Smooth style) or copy and paste a white block over the text.
• Do not include in images something that's for internal use that users will never and should never see.
• Do not create images that require a lot of setup unless it's absolutely necessary. When we localize the Help the translators will have to recreate your scenario in order to capture it in other languages.
• Do not create very wide images. Eliminate white space by cropping the image to show only what's necessary. Images that are too wide cause the text to be off the page. Users will have to use the horizontal scroll bar to see it.
• Populate the <alt> child element for use with screen readers. See the last section for more details.

Capturing Images using Snagit

The directions below assume you're using SnagIt to capture images.

1. When you have identified a screen that you want to capture as a screen shot for inclusion in content, do one of the following:
   1. Open the Snagit desktop application and select the red Capture button.
   2. From your Windows keyboard, press the FN + Print Screen buttons.
2. Use your mouse to select a window or area of your screen that you want to capture, then left-click your computer mouse.
3. If needed, adjust the area by dragging the corners of the highlighted box. Remember to crop out white space and unnecessary parts of the image.
4. Click the Camera icon to screen capture your selection.
5. After capturing an image and viewing it in the Snagit editor, navigate to Image > Resize Image to set the image resolution to 96 DPI (Dots Per Inch).
6. Edit your image as necessary and save the file to your local drive using a JPG extension.

Boxes

Put a box around something within an image to make it stand out:

1. Capture the image.
2. In the SnagIt Editor, click Shape Tool
3. In Shape click the first shape (Rectangle).
4. Set Outline color to magenta 50: #C76CB8.
5. Set Opacity to 100%.
6. Set Line width to 4 pt.
7. Use No Fill and Shadow in bottom right corner.

Capturing MDM images

If you're capturing images of the MDM application for insertion in the MDM reference guide, use the Mozilla Firefox browser and Zoom Out one level from the default.

Image file naming conventions

Name a screen capture with: img- for screenshots and art- for anything else (line art, flow diagrams, etc.) followed by area (int-, hub-, api-, cmn-)

Follow this with the title as it appears (for a screenshot) or a logical title for line art (whatever makes sense)

Examples:

• img-hub-parameter_value_sf_id
• art-hub-xaction_create_mr4_link
• img-cmn-platform_login
• img-atm-Search_field

Alt text

Standards for creating alternative text:

• Every image element needs alt text. Keep vigilant for small icon images that may be easy to miss.
• End all alt tag text with a period.
• Describe the information, not the picture.
• Keep descriptions as short and succinct as possible.
• For consistency when labeling icons, search/locate the icon's GUID. Use the description given in the icon's naming convention.
• You do not need to state "photo/image of..." in the alt text. The screen reader will infer the element is an image.
• If the image contains text, the alt text should repeat the text word-for-word.
• To minimize redundancy, you typically do not need to re-describe what is already explained in the introductory text to your image.

For different types of images:

• Would the user miss something important if you remove the image? If so, these types of informational images require more descriptive alt text.
• Active images are those that perform some type of functionality, i.e. where an image is the only content of a link. In these cases, describe the action the image performs.

Note tags

There are levels of severity for notes. From most severe to least severe, the levels are:

• Caution
• Important
• Tip
• Note

Caution

Caution notes are items that we want to caution against someone doing. A Caution note is used when cautioning a user to be sure before taking a specific action.

Important

Important notes are the least severe notes that receive coloring, calling out their importance. They are calling attention to the user about something and align with information alert labels in platform. Examples: behavior differs between UI mode and source mode; selecting an option that won't work as expected; release-note updates that could break existing working things within platform where there is a workaround.

Tip

Tip notes are used to provide usage tips to the user. Example: suggesting each user has their own unique platform user within the account to avoid overriding Home page customizations of other users.

Note

A Note is the least important note type. If a note tag cannot be given one of the more important types, strongly consider whether this is really a 'note' or if it's just another paragraph. In most cases, notes are really regular paragraphs and do not need to be called out specifically.

The only two current approved use cases for a plain Note are:

• Companion changes, off-cycle releases, etc. within the release notes
• When a 'note' disrupts the flow of information so it's not easy to make it a paragraph, but it is important to call out and it doesn't fit in with one of the other more specific note types

Hyphen versus spaces

Phrases used as adjectives should be hyphenated, whereas phrases used as nouns or verbs should not (e.g. time-out is hyphenated as an adjective, and "time out" as a noun is not).

Always one word or two words, never hyphenated

• When documenting UI labels, mirror the case in the UI label.
• Do not capitalize file name extensions.

Capitalizing operations

How to capitalize Create/CREATE, Delete/DELETE, Get/GET, Query/QUERY, Update/UPDATE, Upsert/UPSERT.

• When used in operations in SQL statements, use all caps (GET).
• When used in the platform API, use all caps (GET).
• When used in actions in connector operations, they appear in the Platform UI as initial capped, so use initial caps (Get).

Do

• Within sentences, spell out numbers less than 10
• Use "you" rather than "the user" (however, we must distinguish between account administrators and users in some contexts)
• Use "topic" rather than "page" or "article" while referring to other pages
• Use forward slashes when documenting directory paths (c:/boomi atomsphere/conf). Although Windows uses backslashes, all other operating systems use forward slashes; many of our users use Linux, and URLs use forward slashes.
• When linking to another topic, if the link can't be embedded in the sentence, say "refer to <topic_name> for more information" (do not use "see" or anything other than "refer to").
• While documenting tasks:
  • Heading names should not be the name of a screen/UI or process. They should reflect what the topic or task is about. Example: use "Adding your email", not "Email ID Screen".
  • Use gerunds in the heading (a verb form ending in "ing" that functions as a noun). Ex. "Adding an XYZ to your process".
  • Use numbered lists for steps that must be done in a sequence.
  • Use bulleted lists where sequence does not matter.
  • If a task step involves choices, have the step say "Select one of the following:", followed by the choices below it.
• While documenting APIs:
  • Refer to an API call as a "request"
  • Refer to the outcome of an API call as a "return"
  • Refer to the content of what is returned from a Query request as "results" or "query results"

Do not

• Do not use contractions. For example, use "cannot", not "can't". Contractions don't translate well.
• Do not use the ampersand (&) in sentences. Use "and". Exceptions: a UI label uses "&" for brevity, or the "&" is present in code.
• Do not use "please", "sorry", or "thank you" in documentation. Exception: very rarely, if we've inconvenienced the user (e.g. "Please wait." while the UI fetches data) — mostly a UX writing consideration; check with your editor if you feel the urge.
• Do not use "IP" or "IPs". Use "IP address" and "IP addresses," respectively.
• Do not use "aka". Spell it out.
• Do not use vague modifiers like "just" or "simply" that may trivialize complexity.
• Do not start sentences with "We" or "I." Documentation should stay product- and user-focused rather than first-person. Lead with the product or service name instead (for example, "Boomi introduced…" rather than "We introduced…").
• Do not disclose product roadmaps, future planned releases, internal ticket numbers/language, or other internal-only information in any customer-facing content. If a feature or fix is planned but not yet available, you may say "<feature/fix> is planned for a future release" — nothing more (no dates, timeframes, or approval status).

Documentation Best Practices

• Start with use case-driven overviews: What can the user achieve?
• Consistent and Minimalist: Brief and to the point. Start with what customer needs to know and don't use flowery language just to fill space. Less is more.
• Headings/Titles: Must reflect what the topic or section is about. E.g. "working with components" vs "Integration components".
• Highlight integration patterns, data flow diagrams, and system architecture.
• Document limits and scalability (e.g., rate limits, payload size, data retention).
• Do not write long topics: consider breaking up long topics into a series of smaller ones.
• Do not add unnecessary screenshots and topics that just describe a UI screen.
• Provide change logs and migration guides for API versioning.
• Do not use in-line icons in documentation. Instead, say the icon's name in italics. E.g. "Click the "X" icon to delete" or "Click the gear icon to view and change your settings".
• Offer quickstart guides, video walkthroughs, and sandbox environments.

Common Pitfalls to avoid

• Don't assume customers understand system boundaries between integrations.
• Do not use platform-specific jargon without context.
• Don't neglect setup/configuration errors in troubleshooting sections.
• Don't mix product UI and API terminology inconsistently.
• Do not write long pages without navigation — use collapsible sections or tabs for clarity.

Avoid abbreviations where possible. Commonly used abbreviations are not read correctly by screen readers or do not translate into other languages. For example, the term "e.g." is frequently pronounced as "egg" by screen readers. Use spelled out terms as shown in the following examples:

Fun fact: In 2016, the British government announced it was removing all abbreviations from the entirety of their website.

Do Not Need to Spell Out

We can use the following commonly used abbreviations and acronyms in Help without spelling them out. Note the capitalization.

Using Service & platform name consistently

• Use Boomi as a prefix with the service name on first usage (for example, Boomi Integration). After that, just use the service name without the Boomi prefix (for example, Integration).
• Use Boomi + service name in the heading of the Getting Started topic for the service (for example, Boomi Integration). After that, use the service name, without the Boomi prefix (for example, Integration).
• On the helpsite home page:
  • On the navbar, use the service name, without the Boomi prefix. For example, just say Integration.
  • In the intro box/card for each service, use just the service name, without the Boomi prefix. For example, just say Integration.
• Only capitalize "platform" when referring to the "Boomi Platform."

Using Boomi terminology consistently

References to account features

When a feature is available for a customer's account, always state "To enable this feature, contact your Boomi Account representative". Do not refer to support and correct doc instances where this is the case.

Grammar and Mechanics

Active voice — Use active voice. Active voice means a sentence has a subject that acts upon its verb; passive voice means a subject is the recipient of a verb's action. Example — Correct: "Boomi recommends placing the agent name in the speech bubble." Incorrect: "Agent name is recommended to display in the speech bubble." Tip: an easy fix for passive voice is removing phrases like "may be used" or "that is being" and turning the sentence active. Do not open a sentence with a form of "to be" followed by a past participle (was, were, has been, have been + verb) — that's a reliable tell for passive voice.

Present vs. Past Tense — Use present tense for general usage. Use past tense for change logs or historical context.

Comma — Use commas between non-essential clauses. E.g. "Johny, who is Martha's cousin, fell in the pool."

Oxford comma — Use Oxford commas in lists: "Enable logging, data transformation, and authentication."

Acronyms — Spell out acronyms and abbreviations on first use: "Integration Platform as a Service (iPaaS)".

That vs Which — Use "that" if the preceding phrase is not set off with a comma; if there is a comma, use "which". Correct: "This approach creates reusable components that contain connection settings." Correct: "The screen passes the request to AIF, which performs additional authentication."

Structure and formatting

• Headings — Reflect logical product flows (Onboarding, Authentication, Integration, Monitoring). Should reflect what the topic is about. If the heading is a question, it should contain a question mark.
• Dates — Spell out the month followed by a comma, then the day and year. E.g. April 29, 2025.
• Lists — Numbered for anything that needs to be done in a specific order/sequence. Bullet points for features and conditions where sequence doesn't matter.
• Tables — Essential for endpoint parameters, pricing tiers, permission roles.
• Emphasis — Italics for emphasis, business-logic terms, and topic names when referring to other topics. Bold for UI elements or alerts. Monospace for code, paths, CLI commands, or environment variables.
• Capitalization — Use sentence case for titles. Capitalize product names. Don't use all uppercase except for abbreviations always written in all-caps, or code that uses all-caps.

Technical Terminology

• Use accurate terminology specific to iPaaS/SaaS contexts: "connector", "endpoint", "workflow", "tenant", "instance".
• Clarify service-specific terms: distinguish between "account", "organization", "workspace", etc.
• Maintain terminology consistency across multi-tenant architectures.
• Provide tooltips, glossaries, or expandable definitions in UIs and portals.

Code and Syntax

• Highlight integration examples with REST APIs, GraphQL, or Webhooks.
• Provide end-to-end use cases (e.g., "trigger on Salesforce update, push to Slack").
• Include authentication samples (OAuth 2.0, API keys).
• Use code blocks for attribute names and SDK snippets in multiple languages (e.g., Node.js, Python).
• Wrap code/syntax with backticks — single backticks for URLs, attribute names, method names, API names, and error types (e.g. TradingPartnerComponent API, extensionGroupId, NullPointerException); three backticks for code blocks, with the language specified (e.g. ```JSON).
• Always ensure the code/syntax is error-free and compilable; check with developers to review code content.
• Use placeholder values in angle brackets or curly brackets depending on context. For REST OpenAPI, use {} (e.g. {api-token}). For cURL/CLI, use <> (e.g. <workflow-id>).

Example:

curl -X POST https://api.acmeconnect.com/v1/workflows/<workflow-id>/run \
  -H "Authorization: Bearer {api-token}"

Accessibility and Inclusivity

• Use inclusive terms: don't use "blacklist/whitelist" — use "allowlist/blocklist".
• Do not use gender-specific terms (e.g. He/She) — use they, them, user, etc.
• Add alt text and captions for architectural diagrams and GIFs.
• Do not use region-specific idioms; write for a global audience.
• Ensure documentation tools and portals comply with WCAG standards.

Using UI terms consistently

Verbs

It's best to use the verb that matches the one used in the UI.

Trademarks

Per the Microsoft Writing Style Guide, trademark symbols are not used in Help or other software elements. Use trademarks in printed documentation on the cover/title page and the first mention in the main text; on web pages, use trademarks at first mention in a multi-page topic or article. Boomi's trademarked terms:

• Atom®
• AtomSphere® or Boomi AtomSphere®
• AtomSphere® Integration Cloud™ (obsolete)
• Boomi® or Boomi, Inc.
• Dell® or Dell, Inc.®
• Dell Technologies®
• The Boomi "b®" logo
• Molecule®
• Other trademarks may be trademarks of their respective owners.

Write other companies' full names to respect their branding guidelines (e.g. don't abbreviate Microsoft as "MSFT"; write "Mac OS <version>", such as Mac OS X). If unsure of correct usage, search for the company's branding guidelines.

Copyrights

The copyright topic is the last chapter in each bookmap. The copyright year needs to be updated manually.

The prefix for a topic name is determined by the subject product.

• int- Integration
• hub- Master Data Hub
• api- API Management
• cmn- shared content (legacy prefix — should not be used on new files)
• atm- AtomSphere content (AtomSphere is no longer used as a Platform name)
• es- Event Streams

Immediately following the prefix is the file title. Words in the file title are separated by underscores. Do not include spaces in filenames — it results in ugly URLs!

Topic name examples

• int-Boomi_Integration_navigation
• api-Downloading_the_local_Broker_installer
• hub-Viewing_domain_data
• cmn-Build_tab (legacy prefix)
• atm-Content_browsing

Image naming

The prefix for an image name has two parts. The first part: img- for screenshots, art- for anything else (line art, flow diagrams). The second part is the subject product (int-, hub-, api-, cmn-, atm-). Immediately following is the title as it appears (screenshot) or a logical title (line art).

Image name examples

• img-hub-parameter_value_sf_id
• art-hub-xaction_create_mr4_link
• img-cmn-platform_login
• img-atm-Search_field

Restrictions

Any topic name that becomes part of a URL address must only use these characters: a-z, A-Z, 0-9, underscore (_), dash (-), period (.). Do not use other characters, such as commas, apostrophes, and parentheses.