In-Product Help

Overview

This guide includes rules for writing in-product help.

Become familiar with the entries in the Editorial Style Guide first, and then consult the entries here for additional guidance. If the title of an entry in this guide is followed by an asterisk, it means that the rule is an exception or addition to the rule in the Editorial Style Guide.

• How to Use Trisoft and XMetal at Autodesk (access required)
• For a word list, view the Acrolinx Term Browser (access required). To request an Acrolinx account see: Acrolinx Instructions and Plug-In Installers (access required).

Writing help content

Keep it simple

Imagine that you are writing for someone who is smart but who does not necessarily have a strong grasp of English. This person often reads English sentences word by word.

To help this reader, use simple language and clear expression:

• Use common words (aim for words understood by most 12-year-olds).
• Define technical terms.
• Avoid jargon, idioms, and humor.
• Strive for clarity and a complete lack of ambiguity.
• Don’t sacrifice clarity for elegant style. Short, choppy sentences are fine.
• Don’t use synonyms in the service of stylistic variation. Users may think that you’re making a subtle distinction. Use one word and stick to it.

Keep the structure simple, too:

• Concentrate on procedural organization.
• Flatten the structure, minimizing hierarchical and design elements.

Don’t be creative for the sake of creativity. Departing from conventions can reduce portability. Before you jump on the innovation bandwagon, ask yourself:

• Does this enhance usability or get in the way? For example, many users find tool clips (tooltips in the form of videos) annoying and turn them off.
• Is this the right way to deliver this content? For example, many users are annoyed by having to watch 2-minute videos when simple text would give the answer in seconds.
• Is this innovation sustainable in an agile development environment? For example, UI-centric innovations quickly become unsustainable when the UI is under constant revision.

Keep it short

Keep it practical

• Provide workflows that give users a path to follow and show users what to expect.
• Keep your focus on the user, not the software.
• Organize by recognizable tasks rather than by tools, menus, or other software anatomy.
• Use real-life examples in text and figures.

Keep it modular

Write for reuse. For example, if a topic applies equally to two products, operating systems, or devices, write it so that it applies to all. Here are some strategies:

Keep your audience in mind

You are generally writing for these customers:

• Creative professionals with five years of experience. Even if they are new to your product, they are already familiar with similarly complex software.
• Experienced developers or administrators.

Assume that they don’t need spoon-feeding. They have mastered platform skills and general industry concepts.

Most customers are in reactive mode. Experienced customers are in your help system because they have a problem that they must solve under tight time constraints.

• What is this?
• How do I do this?
• It’s not working right.

They’re likely to be already frustrated. They want a quick answer so that they can get back to work and be productive.

Few customers are in proactive mode. What about the novice who knows little about the product, or the specialized customer-facing a complex task, such as an enterprise deployment? They may be willing to spend more time exploring tutorials, videos, and workflows—content that is more complex and takes longer to digest.

Even so, you should simplify, shorten, and focus the content to the degree possible. Even proactive customers hate to read.

Topic types and scope

A topic is a nonbreaking page with help content. It’s about a focused, specific subject yet gives enough information about that subject to stand alone.

These three building-block topics make up the help system, and you should write them in this order:

• Task topics
• Reference topics
• Concept topics

A topic of correct scope completely answers focused questions (not too specific or too general) that customers really ask. It is neither long and intimidating nor trivial and overly atomized.

• A task topic clearly defines an immediate question or problem and resolves it in under five minutes. Aim for a limit of 500 words.

• A concept topic covers the basics of one clearly defined subject. Customers can digest the concept topic in five to ten minutes. Aim for a limit of 1,000 words.

Topic scannability

Most people hate to read help topics. Even when your topic is complex, you can increase the reader’s chance of success by making the page easy to scan. A scannable topic gives the customer signposts through headings, figures, and bullets. In this way, the customer can quickly grasp the gist of the topic and decide whether to read it.

• Nine steps per task, preferably no more than seven.
• Seven bullets per list maximum.
• Five sections maximum in a nonbreaking help page.
• 150 words and six sentences per paragraph.
• 25 words maximum in a sentence.
• Two consecutive paragraphs are OK. Then interrupt with a section head, a figure, or a list.

These limits are not absolute. There are always outliers that require the bending of rules.

Task topic boilerplates

These guidelines are written in the form of a task.

To write an ordered task

You can begin with an optional introduction or element that sets the context. Don’t use the shortdesc element to repeat the title. Proceed directly to steps if the title sets context sufficiently. Keep your introductions short.

• Use no more than two paragraphs in the introduction and no more than three sentences per paragraph. Don’t repeat the task title directly above the numbered steps.
• Use a numbered list (ordered list) for steps that the customer takes sequentially. Make each step an action that the customer takes, phrased as an imperative (“Do this,” “Change that”). Avoid obvious step results, such as “You see an enlarged version of the model” after the step “Zoom in.” The display of a dialog is usually an unnecessary step result.
• Keep your numbered list as short as possible. Aim for no more than seven steps.
• If the step is associated with a condition, put the condition first: “If your scene materials use bitmaps from different folders, copy all the bitmaps to a common directory.”
• Nest bullets (unordered list) under a numbered step to give conditions or choices of action.
  • Examples:
    • If x, do y.
    • In Revit, do x.
    • In Vasari, do y.
  • Avoid interrupting nested bullets with notes or tips.
  • Keep bullets under a numbered step to a maximum of five.
• You can also nest a bulleted list under a step to give widgets or options. Examples:
  • Option 1 Name. Option definition.
  • Option 2 Name. Option definition with legal values. If there is more than a handful of options, isolate them in a reference topic and include them in “Related references” at the end of the topic.

To group related single-step tasks

You can group single-step-related tasks in an unordered (bulleted) list. However, avoid obvious tasks that are adequately explained by tooltips. Keep the list short; aim for no more than seven items. An example, “To work with tags,” follows:

• To tag an element, do a.
• To tag multiple elements, do b.
• To change the appearance of tags, do c.

Umbrella task topic boilerplate

These guidelines are written in the form of an umbrella task.

To group tasks under an umbrella

The umbrella task aggregates related short tasks in individual sections. Follow these guidelines when naming an umbrella topic:

• If the tasks involve different actions on an object (for example, to cut, add, get, copy, and browse files), use “To work with x” or “To manage x” as a title.
• If the tasks involve only one kind of action (for example, to merge layers in the Property Manager and to merge layers by selecting objects), use a narrower verb, such as “To merge x,” “To change y.”

Put the first subtask in a section

The umbrella task “To work with files” may have these sections:

• Add a file
• Get a file version
• Browse for missing files

The umbrella task “To merge layers” may have these sections:

• In the Property Manager
• By selecting objects

Important: When you create an umbrella task, carefully consider whether one of its sections applies broadly across many application contexts. If so, make it a stand-alone task. For example, if browsing for missing files is a step in several workflows, make that topic a stand-alone task. By contrast, it’s fine to use “To merge layers” as a step in a workflow, because that umbrella task simply gives customers a choice of how to merge layers.

Reference topic boilerplate

There is no single boilerplate for reference material. The nature of the content governs the form it takes (definition lists, tables, function headings, and so on).

Reference topics enumerate, define, and sometimes illustrate widgets (options, commands, tools, attributes, variables, filters, effects, and the like). References can contain these elements:

• Widget names
• Widget definitions
• Subwidgets
• Subwidget definitions
• Screenshots, line drawings, rendered art
• Examples
• Legal values
• Tables
• Lists

Concept boilerplate

These guidelines are written in the form of a concept.

About writing concepts

Introductory material is optional.

• Limit the introduction to two paragraphs of no more than five sentences each and no more than one figure and one unordered list.
• Keep your sentences under 25 words.
• Make sure that the title complies with the titling guidelines.
• Use no more than five sections in a concept, and a total limit of 1,000 words.

Use section heads to give the reader signposts

Paragraph 1. Keep your paragraphs short. Limit yourself to 150 words and six sentences.

Note: Don’t bury essential information in notes. Reserve them for incidental, “nice-to-know” information. You can also use notes for information that is relevant to only a minority of users. For example, if few users run your product on Linux, you can give Linux-specific information in notes.

Paragraph 2. Avoid having more than two paragraphs in sequence. If possible, interrupt three consecutive paragraphs with a list, section head, or figure.

• Use bulleted lists to make content easy to scan.
• Reserve bullets for brief text. Don’t bullet paragraphs of text.
• Don’t place notes between bulleted items.
• The eye can scan seven bulleted items at most. Keep your lists short.

Tip: Tips show customers ways to save time and accomplish work efficiently. Avoid consecutive (“stacked”) tips and notes.

Section heads can distill the content that follows

You can enhance scannability by using section headings followed by multiple paragraphs.

Section heads are not hierarchical. Forget the rule that there must be at least two.

Section heads can signal a new idea or a shift in emphasis

The two-paragraph rule is not set in stone. Don’t automatically insert heads after every two paragraphs.

Art

See Screenshots and illustrations.

Boldface

• Render user-entered values in boldface: Enter d (Delete).
• Don’t use bold for emphasis.

Buttons

A selectable widget on a toolbar, ribbon, or flyout.

• Select or click (not click on) a button. Use select if you are single-sourcing topics for phones and desktops.
• Generally omit the word button: Click Cancel.

See also Dialogs.

Callouts

A callout is a symbol or short string of text connected by a line or arrow (the leader line) to an element in a screenshot or drawing and giving information about that element.

• For localization reasons, it’s best to use numbers for callouts. Then explain the callout number in the caption.
• If the callout leader line leads to text (not recommended), use sentence-style capitalization with no end punctuation.

Capitalization

Note: See Capitalization for more information.

All caps (FULL CAPS)

When to use	Examples
Commands in products (not in menus)	the OPTIONS command
System variables	the AFLAGS system variable
Environment variables	…is controlled by the XNOTIFYTIME environment variable

Title caps

When to use	Examples
Command groups	the Walk and Fly commands
Keys on the keyboard	the Right Arrow key; the Spacebar
Menus; commands and options in menus	File menu; the Width option; the Save A Copy command. (Note that in menus, menu commands, and option names, unimportant words are capitalized.)
Dialogs	Hatch and Gradient dialog
Dialog areas	in the File Listing area
Dialog options (even if they’re not capitalized in the user interface)	Back Face Normal Is Negative
Names of modes	working in Object Snap mode

Sentence case

When to use	Examples
Captions and callouts	Two-dimensional coordinate system
Table titles	Valid wild-card characters
Column headings	in tables System variable

Captions

Optional captions appear below an illustration. If you introduce the illustration with a sentence or phrase, that can serve as the caption instead. Captions or introductions to illustrations are vital for people with diminished vision who use screen readers.

• Explain numbered callouts in the caption.
• Use a period if the caption is a full sentence.
• A good caption explains the purpose of the figure rather than merely describing the figure.

Click and drag

Colons

Note: See Colons.

• Don’t use colons in titles and headings.
• Don’t use a colon after a sentence introducing a figure or screenshot.

Commands

“Command” has two meanings. It can refer to a product-specific command (such as OSNAP in AutoCAD) or an item in a menu.

Use full caps to refer to a product-specific command, such as OSNAP.

Use title case to refer to menu commands or ribbon selections. Capitalize all words, even a and the. Example: Use XEDGES to create the wireframe geometry. Click Home tab > Solid Editing panel > Extract Edges.

Conditional text

• Avoid using conditions directly in a topic.
• Write for the broadest applicability so that you won’t have to mention products or platforms.
• If conditions are necessary, use them only in DITA maps.

Demos

See Videos and screen motion captures.

Dialogs

• Use dialog, not dialog box.
• You open and close dialogs.
• Options are in, not on, a dialog.
• Use this capitalization style: Options dialog, Display tab.

Dialogs often have many tabs and UI widgets. Follow these guidelines:

• When possible, name the option without stating the type: Omit radio button, checkbox, box, and so on.
• Refer to a box that accepts text as a box. (You can use text box in developer documentation that explains how to create UI elements.)
• Refer to a list box as a list. (You can use list box in developer documentation.)
• Don’t use the term field to refer to an option.
• Append the word option only if it adds clarity.

Ellipsis

Omit the ellipsis points in button and menu command names when referring to them in documentation.

Figures

See Screenshots and illustrations.

Files, filenames, and filename extensions

Use italic and lowercase for filenames: the newdrawing.dwg file.

When referring to files of a certain type, don’t use the “dotted” lowercase filename extension:

The need to document filename extensions is rare. Example: …files with the .rtf filename extension.

The filename extension, when used without a filename, is not italic.

Headings and subheads

The terms heading, subhead, and title are synonymous in this guide. (Don’t confuse the term with the tag names in the code.)

Use sentence case.

• Reword or shorten so that the most important words in the title aren’t truncated in search results. For example, use “To change the display of graphic layers” rather than “Make view-specific changes to the display of graphic layers.”
• Name according to what the user does, not what the UI says: “To revert to a previous version” rather than “To use the Rewind tool.”
• Make sure that the title gives enough information to make sense outside a TOC context. “About placement settings for beam annotations” rather than “About placement.”
• Phrase in the language your readers use: “To import a site from a Google Earth file” rather than “Import KML/KMZ, build, and publish model.”
• Don’t repeat the title before the numbered steps in a task or in the shortdesc.

Icons

When you use icons inline in text, place the name of the icon before the image: Click the Reports icon . Always name the icon; don’t use just the image.

Exception: If you define icons in a table with the column headers “Icon” and “Definition,” it’s OK to use only the icon in the first column.

Illustrations

See Screenshots and illustrations.

Italics

Italicize the following:

• Filenames: the example.txt file
• Placeholders in the UI: Select Project tab > <project name>
• Placeholders in paths: C:/Documents and Settings/<username>/Desktop/<filename>

Keyboard sequences and keys

Follow these guidelines for keyboard sequences:

• To indicate that the customer needs to press two or more keys at the same time, use a plus sign without spaces between the elements: Ctrl+Alt+Delete
• To indicate that the customer needs to press keys in sequence, use a space: Esc Shift+Q

Don’t use key names as verbs.

Exception: You can use key combinations that use click as verbs: right-click+D

Follow these guidelines for keys:

• You press (not depress) keys.
• Express OS differences in natural language, using parentheses: Press Ctrl (Windows) or Command (macOS). Put the Windows option first.
• In general, capitalize the names of keys.
  Exception: Don’t capitalize unnamed keys, such as backslash, forward slash, ampersand, and so on. But do capitalize Spacebar.
• Here’s how to capitalize the names of some frequently used keys:
  • Alt (Windows)
  • Backspace
  • Caps Lock
  • Command (macOS)
  • Control (macOS)
  • Ctrl (Windows)
  • Delete
  • Down Arrow
  • Enter (Windows)
  • Esc
  • Fn (but F3, F12)
  • Insert
  • Option (macOS)
  • Page Down
  • Page Up
  • Print Screen
  • Return (macOS)
  • Shift
  • Spacebar
  • Tab
  • Up Arrow
  • Windows key (no need to use the multipaned icon)

For more information, see Operating systems, Paths, Keep it modular, and Parentheses.

Links

Be thoughtful when deciding which links to place at the bottom of a topic. Often it’s better to point to orthogonal content areas that the user may not be aware of rather than to a family of closely related topics. For example, suppose your topic is “To create a block.” Placing “About blocks” in the “Related topics” list is probably not as useful as including “About dynamic blocks” in the list. The person reading “To create a block” and needing more information about blocks can easily find “About blocks” in search results or the TOC. However, that person may not be aware that dynamic blocks exist.

• Don’t use inline links in topics, except to external sites (marketing, and so on).
• Use Next and Previous links in tutorials.
• Place links at the bottom in the appropriate bucket: “Related tasks,” “Related concepts,” and “Related references.”

Lists

Lists make information easier to scan. Choose your list type according to the information it contains:

• Numbered lists (ordered lists). For information that users read and process in sequence. Use for task-like topics.
• Definition lists. For information organized as terms and definitions. Use for options, commands, effects, and so on.
• Bulleted lists (unordered lists). For related information. Use for a list of supported file types, choices that aren’t sequential, related points, and the like. Also appropriate for nonconsecutive task steps, for example, “To tag an element…,” “To tag multiple elements…,” and “To change the appearance of tags….”

Follow these guidelines when you create lists:

• A list includes at least two items.
  Exceptions: Some tasks have only a single step, and a link list can have only one link.
• Use parallel structure in lists, but break this rule if it leads to wordiness.
• Capitalize the first word of each item in a bulleted list, even if it is fragment.
• Make your list items concise and easy to scan, about 30 words. Don’t bullet long paragraphs of text.
• Use end punctuation only if the items are complete sentences. If one item in the list needs a period, use periods after all items.

Movies

See Videos and screen motion captures.

Notes and tips

Notes alert the user to “nice-to-know” information. You can also use notes for material of interest to a small portion of your audience, such as Linux users. Tips show users ways to save time and accomplish work efficiently.

• Use notes or tips sparingly between the steps of a task. Never place a note directly after a tip, or a tip after a note.
• Notes and tips follow a step or paragraph of text. Avoid using one after a heading, and never use one after an illustration.
• Keep notes and tips to one paragraph only. If you need more than one paragraph, restructure the content and include it in the body of the topic.

Numerals

For 0, use the numeral. But: nonzero value.

Operating systems

• Assume that your users know operating system conventions. Don’t document them.
• In, on, and for: Feature no longer available in Windows; runs on macOS; Autodesk Maya for Linux.
• Use macOS, not Macintosh or Mac, and Windows, not PC.

Parentheses

• Precede optional steps with “(Optional)”: 4. (Optional) Specialize your installation by choosing configuration options.
• Use parentheses for OS, product, and cross-product differences. Examples:
  • Choose X (Windows) or Y (macOS).
  • Choose X (Revit) or Y (Revit LT).
  • Export from either product A (Export > CSV) or product B (Send To > CSV).
• End punctuation: Inside or outside the final parenthesis? Placement depends on whether the words in parentheses constitute a sentence on their own belong to the main sentence. Examples:
  • Autodesk won the award for the greenest company in the world. (Don’t share externally yet.)
  • Autodesk won the award for the award for the greenest company in the world (as determined by the Green Council).

Paths

A path is a series of nested folders in which a file resides.

• Don’t say that a file is in a path. Say that the xyz file is in, for example, /Applications/Autodesk/<product name>.app/Contents/macOS/.
• Use path rather than path name.
• Ordinarily, use forward slashes (the macOS convention) rather than backslashes (the Windows convention).
  Exception: If the user must enter the path, use backslashes in Windows-only topics, or show Windows and macOS variants in a topic that applies to both operating systems. Example: Enter AcadJobsJobs$prj (Windows) or /AcadJobs/Jobs/$prj (macOS).

Placeholders

Use italic and angle brackets for placeholders.

• Placeholders in the UI: Select Project tab > <projectname>
• Placeholders in paths: C:/Documents and Settings/<username>/Desktop/<filename>
• Parameters (answer), types (int), and variables in functions and methods are not placeholders. They are not italicized.

Platforms

A platform is a combination of operating system, product, and device. See Keep it modular.

Product names

• Legal maintains a list of current product names here: Commonly Referenced Autodesk Products and Services.
• When possible, avoid mentioning the product name in help topics used in multiple releases and multiple products. See Keep it modular.
• Don’t use internal code names in documentation.
• Don’t abbreviate product names or use them as plurals or possessives.

Quotation marks

• Don’t use quotation marks for UI elements. Capitalize every word of the UI element instead.
• Use quotation marks for error and system messages. Example: You see the message “Lost license handler.”
• Ordinarily, periods and commas go inside quotation marks. Break this rule for clarity with code elements that contain quotation marks. Example: username$ = "Mary".
• Don’t use quotation marks after called, stands for, or known as. Use italic instead. Example: “Inverse kinematics, also called puppeting,…”

Scannability

See Topic scannability.

Scope of topics

See Topic types and scope.

Screenshots and illustrations

• Screenshots and illustrations enrich the text and don’t simply repeat it.
• Ensure that every illustration has a pedagogic purpose and is not merely decorative.

When to use a screenshot

• When it would take many words to describe an abstract, confusing concept, such as handles on an inverse kinematics (IK) skeleton. (Search for “IK handles” in Maya help.)
• To show a hidden item in the UI.
• To provide context about completing a task.

When not to use a screenshot

• To show every screen in a simple task.
• When you have previously shown another version of the same screen.
• When you can describe the result unambiguously in words.

Search optimization

• “Front-load” topic titles with the most important words, and follow guidelines for titles.
• Use a short description (shortdesc) when the title does not fully describe the content of the topic. For example, in the topic “To draw a geometric figure,” you can add the shortdesc “Draw a circle, rectangle, or triangle” so that the user searching for “draw a circle” sees this topic high in search results.
• Provide search terms as keywords in metadata, especially synonyms.
• Mention important terms and concepts early in the topic, preferably in the first paragraph.
• Remember that text in images is not searched but that captions are.
• Videos are not searchable. Provide keywords and introductory text explaining the purpose of the video.

Short descriptions

• Short descriptions (shortdesc elements) are optional. Don’t use them merely to restate the title.
• Remember that Google ignores XML metadata. If you use keywords or other attributes to enhance SEO in AKN, include them, as appropriate, in the short description as well.
• Use shortdescs to provide topic context not given by the title. For example, the topic “To use perspective view” may have the shortdesc “Change to Perspective mode, navigate in Camera mode, and set distortion.”
• Use shortdescs to enumerate the tasks in an umbrella topic. For example, the topic “To work with dimension styles” may have the shortdesc “Apply, create, and modify dimension styles.”

Start versus launch

• Use start instead of launch (a nautical metaphor) in help text. Example: Start (restart) your product or software.
• In buttons, use Start instead of Launch.

Tables

Reserve tables for information that is best displayed as a simple data grid. Avoid using them to achieve special formatting effects.

• You can use short bulleted lists in table cells, but not numbered lists. Don’t bury tasks in table cells.
• Keep text in table cells short. If you need a paragraph in a cell, then a table is the wrong way to deliver the information.
• You can use icons in table cells, but not screenshots or line art.

Tips

See Notes and tips.

Titles

See also Headings and subheads.

Singular or plural?

• Use the singular for most tasks. Example: To edit a reference path.
• Use the plural when common sense so dictates. Example: To delete multiple data points.
• Use the plural in umbrella tasks. Example: To work with files in Vault.
• Use the plural in concepts about a category of objects. Examples: About section objects. About DIN rails.
• Use the singular in concepts about abstract ideas. Example: About redline geometry.

Titles by topic type

UI elements

See Buttons, Commands, Dialogs, and Capitalization.

Versions and releases

We are moving to a releaseless model, but follow these rules if you must mention past releases:

• Release is not part of the product name.
• Avoid mentioning the release or version whenever possible. You can mention them, of course, when comparing functionality or talking about updating from one version to another.
• Use earlier and later, not lower and higher, when talking about releases: Not available in AutoCAD 2014 or earlier.
• Users who subscribe to a product receive updates. Releases don’t apply in the subscription model going forward.

Videos and screen motion captures

Use videos and screen captures to convey information that is difficult to give in text alone. Don’t use them merely for the sake of novelty or entertainment value:

• They take more time to consume than text alone and waste users’ time when used unnecessarily.
• They present SEO challenges, because search engines can’t crawl their content.
• They take more time to develop than text topics, and they can quickly become obsolete with agile software development.
• They are expensive to localize. If there is no localization budget, your content won’t reach some of your audience.

For these reasons, make sure that you have a legitimate business need for a video before you embark on making one. Observe these rules:

• Avoid redundancy. If an existing text topic explains a subject adequately, you don’t need a visual version.
• Don’t use sample content in a video unless its creator grants Autodesk rights.
• To enhance search, provide a short text description of every video.
• Keep it short. People can’t follow videos that capture many steps. And they don’t have the patience to watch clips lasting more than 2 minutes.

Why use a video?

• Use videos to introduce or evangelize new products and features.
• Use videos when a subject generates a high volume of support calls.
• Use videos when the subject is easier to illustrate than to describe or when the task or subject is especially confusing.

When do you stick to text?

• Text is always the first choice. Use a video only when you can make a business case for it.
• Use text when the content is straightforward and you can explain it clearly in words.

What about localization?

• Don’t localize if the UI isn’t final and the content isn’t stable.
• If you intend to localize a screen capture, use text bubbles in addition to audio. There may be insufficient budget to localize audio.

Workflows

Workflows string together disparate tasks that are performed in sequence or trace how team members act on data as it flows through a system. For example, “Workflow: collaborating through mockups” could contain the tasks “To share a mockup,” “To annotate a mockup,” “To find clashes in mockups,” and “To reposition components in a mockup.”

• Don’t confuse workflows with umbrella tasks, which some help systems call “basic workflows.” For example, a topic that tells the user how to open a mockup in three different contexts is an umbrella task rather than a workflow.
• Workflows are not simply cross-application tasks. For example, in Revit and AutoCAD, the Application menu allows the user to export files to Showcase and 3ds Max for rendering. However, this is a single task accomplished in two places.
• Individual tasks in the workflow are sometimes completed by different members of a team. For example, as data flows through BIM 360, a project manager interested in containing costs and an engineer interested in resolving clashes look at files at different stages and for different purposes.
• Single-source the individual tasks in a workflow if they are also basic tasks. For example, suppose “To annotate a mockup” is a task in a workflow. When the reader encounters it in the context of a workflow, the only links in it are Next (which may lead to “To find clashes in mockups”) and Previous (which leads to “To share a mockup”).
• Search always leads readers to the beginning of a workflow or to a stand-alone task, and never to a task in the middle of a workflow. For example, if the user searches for “To annotate a mockup,” search should yield both “Workflow: collaborating through mockups” and the stand-alone instance.