© 2021 Autodesk, Inc.
In-Product Help Style Guide

How to use this guide

This guide includes rules for writing in-product help. It’s based on the rules of the Editorial Style Guide.

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.

CXD service desk

How can we help? Use the CXD service desk to report issues with this style guide, such as missing content or usability concerns, or to propose new guidelines.

Tips on using the service desk.

For questions on the Editorial Style Guide, contact missy.roback@autodesk.com

Table of contents

Writing help content Keyboard sequences and keys
Topic types and scope Links
Topic scannability Lists
Task topic boilerplates Movies
Umbrella task topic boilerplate Notes and tips
Reference topic boilerplate Numerals
Concept boilerplate Operating systems
Art Parentheses
Boldface Paths
Buttons Placeholders
Callouts Platforms
Capitalization Product names
Captions Quotation marks
Click and drag Scannability
Colons Scope of topics
Commands Screenshots and illustrations
Conditional text Search optimization
Demos Short descriptions
Dialogs Start versus launch
Ellipsis Tables
Figures Tips
Files, filenames, and filename extensions Titles
Headings and subheads UI elements
Icons Versions and releases
Illustrations Videos and screen motion captures
Italics Workflows
   

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 my most 12-year-olds).
  • Define technical terms.
  • Avoid jargon, idioms, and humor.
  • Strive for clarity and 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 (tool tips 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

  • Use short sentences. Use simple subject-object structures, and avoid long clauses. Don’t use the subjunctive mood (change “The dialog requires that the user enter a valid value” to “Enter a valid value” or “The value must be valid”).
  • Delete unnecessary words. You reduce Autodesk localization costs, and you save the user time.

    NO: When the “Java needs your permission to run” message displays at the top of the browser, select “Run this time.”
    YES: When Java asks permission to run, select Run This Time.

  • Short trumps perfect. When necessary, break style conventions that lead to empty words. For example, to shorten, you can ignore the convention that list items must be either all fragments or all full sentences. Also, shield the user from unnecessary details and complexity.
  • Single-source it. Don’t repeat the same thing in different contexts. Eliminate redundant text of more than a sentence or two.
  • One way. Document only one way to perform a task. For example, don’t document various ways to zoom, and don’t give keyboard shortcuts in addition to UI instructions. (Exception: If the way to perform a task is different in two different application contexts, document both.)
  • Not an encyclopedia. Abandon the encyclopedic approach. Don’t document self-evident options, trivial tasks easily inferred from tool tips, or operating system tasks and conventions.
  • No introduction necessary. Delete topic introductions that restate the title in different words. Similarly, don’t add a shortdesc (short description) element that restates the title.
  • Limit visuals. Make sure that illustrations and videos serve a learning purpose. Use them to enrich rather than repeat the text. Don’t use an illustration for what you can describe briefly in text. For more information, see Screenshots and illustrations and Videos and screen motion captures.

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:

  • Avoid using the product name. Instead of saying how the product works, say what the customer does.

    NO: In Revit LT, you can’t add parameters…

    YES: You can’t add parameters…

    NO: Revit treats the data imported from Trimble as a large block of geometry that resists being manipulated…

    YES: You can’t manipulate data imported from Trimble as a large block of geometry…

  • Talk about a feature that is more specific than the product: the menu, the dialog, the folder, and so on.
  • Use the passive voice sparingly to remove product distinctions. (Exception to Autodesk style.)
  • Express product, operating system, and platform differences in natural language in the topic.
  • If your text applies to several devices, use the most general language you can. For example, use select rather than click or tap.

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.

back to top

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.
  • A reference topic defines options, commands, attributes, and the like in a scannable format, omitting self-explanatory options. Reference topics can’t be constrained by word limits, but try to group options for scannability in long reference topics.

TOO NARROW: “To add a mesh crease,” “To change the crease value,” “To remove a mesh crease”

CORRECT SCOPE: “To work with mesh creases”

TOO NARROW: “To switch to the big tour building wheel” and “To switch to the mini tour building wheel”

CORRECT SCOPE: Either a single task or no task at all. A concept about wheels could mention that you change wheel views by right-clicking.

TOO BROAD: “Mold design”

CORRECT SCOPE: “About family molds”

back to top

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.

back to top

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 <shortdesc> element that sets 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.

  1. 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.
  2. Keep your numbered list as short as possible. Aim for no more than seven steps.
  3. 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.”
  4. Nest bullets (unordered list) under a numbered step to give conditions or choices of action.
    • 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.
  5. You can also nest a bulleted list under a step to give widgets or options.
    • 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 it 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 tool tips. 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.

back to top

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.

back to top

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

back to top

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.

back to top

Art

See Screenshots and illustrations.

back to top

Boldface

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

back to top

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.

back to top

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.

back to top

Capitalization*

When to use Examples
ALL CAPS (FULL CAPS)  
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  
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  
Captions and callouts Two-dimensional coordinate system
Table titles Valid wild-card characters
Column headings in tables System variable

*See the Editorial Style Guide for the full entry.

back to top

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

NO: An exploded block

YES: Explode a block to work with its components.

back to top

Click and drag

NO: click on, left-click, LMB-click

YES: click

NO: click and drag, LMB-drag

YES: drag

NO: RMB-click, RMB-drag

YES: right-click, right-drag

NO: MMB-click, MMB-drag

YES: middle-click, middle-drag

back to top

Colons*

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

*See the Editorial Style Guide for the full entry.

back to top

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.

Use XEDGES to create the wireframe geometry. Click Home tab > Solid Editing panel > Extract Edges.

back to top

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.

back to top

Demos

See Videos and screen motion captures.

back to top

Dialog*

  • Use dialog, not dialog box. Exception to the Editorial Style Guide.
  • 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.

back to top

Ellipsis*

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

*See the Editorial Style Guide for the full entry.

back to top

Figures

See Screenshots and illustrations.

back to top

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:

NO: .rtf files

YES: RTF files

The need to document filename extensions is rare.

…files with the .rtf filename extension

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

back to top

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.

back to top

Icons

When you use icons inline in text, place the name of the icon before the image: Click the Reports icon <image>. 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.

back to top

Illustrations

See Screenshots and illustrations.

back to top

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>

*See the Editorial Style Guide for the full entry.

back to top

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.

back to top

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

back to top

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

*See the Editorial Style Guide for the full entry.

back to top

Movies

See Videos and screen motion captures.

back to top

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.

*See the Editorial Style Guide for the full entry.

back to top

Numerals*

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

*See the Editorial Style Guide for the full entry.

back to top

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.

back to top

Parentheses

  • Don’t hide important information in parentheses.

    NO: Save your settings before you close the options file. (If you don’t, you lose all your work.)

    YES: Save your settings before you close the options file. Important: If you don’t save the settings, you lose all your work.

  • Precede optional steps with “(Optional)”: 4. (Optional) Specialize your installation by choosing configuration options.
  • Use parentheses for OS, product, and cross-product differences:
    • 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.
    • 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.

    Enter \AcadJobs\Jobs$prj (Windows) or /AcadJobs/Jobs/$prj (macOS).

back to top

Placeholders

Use italic and angle brackets for placeholders.

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

    int divide() {int answer = 35 \ 7; return answer;}

back to top

Platforms

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

back to top

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.

*See the Editorial Style Guide for the full entry.

back to top

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: 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: username$ = "Mary".
  • Don’t use quotation marks after called, stands for, or known as. Use italic instead. “Inverse kinematics, also called puppeting,…

*See the Editorial Style Guide for the full entry.

back to top

Scannability

See Topic scannability.

back to top

Scope of topics

See Topic types and scope.

back to top

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.

back to top

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.

back to top

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

back to top

Start versus launch

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

back to top

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.

back to top

Tips

See Notes and tips.

back to top

Titles*

See Headings and subheads.

Singular or plural?

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

Titles by topic type

  • For tasks, use an infinitive.

    To load or reload a file reference

  • For concepts, use About.

    About drawings and templates

  • For references, include reference.

    Express tool reference

  • For workflows, use a gerund and the word workflow.

    Workflow: collaborating through mockups

  • For tutorials, use an imperative or noun phrase and include the word tutorial.

    Tutorial: insert PLC modules in connective devices; Tutorial: adaptive clearing

*See the Editorial Style Guide for the full entry.

back to top

UI elements

See Buttons, Commands, Dialogs, and Capitalization.

back to top

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.

back to top

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.

back to top

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.

back to top