Content types in Experience League documentation

This page helps you understand deliverable types and content types (and where to put them).

As you author content, think about what type of content you are creating, everything from a broadly defined deliverable type (guide, tutorial, course) to the type of content on the page (overview, concept, task). How you arrange content on the page facilitates readability and the ability to scan the page and quickly find information.

Deliverable types

A deliverable is what we call a published work–a user guide, tutorial, or a course. Not all deliverables are defined the same. Here are definitions of the types of deliverables we publish on Experience League (and some we don’t):

Deliverable	Description
User guide	Generally, these deliverables are feature guides for end users and include the formal information manuals about how to use Adobe products. Example user guide. User guides provide structured information covering product overviews and the basic concepts and tasks about features and can be published for specific audiences like administrators, end users, implementors, and so on. Adobe’s product teams are responsible for documenting the product in user guides and maintaining the accuracy of this information. Some Adobe history: In Experience Cloud, user guides historically were the only deliverables that the product documentation teams authored and published. If a useful blog or video tutorial from subject matter experts existed, writers referenced that information in user guides. Recently, product experts in Experience League have been creating tutorials and courses to fill an important requirement from customers wanting to use Experience Cloud solutions for use cases and cross-solution workflows. Publishing tutorials (described below) separately from the user guides is useful for these customers. While user guides and tutorials should cross-reference each other liberally where appropriate, it’s important to avoid double-sourcing of information. See tutorial for important information about the differences between these content types.
Reference guide	In software, these are developer docs, including Application Protocol Interface (API) and software development kit (SDK) documentation. API documentation is a technical content deliverable, containing instructions about how to effectively use and integrate with an API. An SDK is a set of software development tools used for developing applications for a specific device or operating system. Developer docs are reference material usually in table (or similar) format. Developer docs are published to adobe.io.
Tutorial	A tutorial is often defined as a set of instructions to help a user understand how to do something, why you do something, or when you do something. If a user guide documents how to use a bread maker, a tutorial tells you how to bake sourdough bread. Here’s an example of a tutorial. Tutorials describe how to use selective solutions, products, or features together to accomplish a specific task. Tutorials can be either video or text-based and can range from a single article or video to a larger, multi-step set of text and video-based guidance. For example, a tutorial might show how to use Adobe Experience Platform Launch to implement Platform and Target, create a schema, ingest data, analyze the data using queries and other tools. Then it could take you to Target to create personalized content based on what you learned. In Experience Cloud documentation, tutorials augment product documentation (user guides) but should not duplicate information. Tutorials dive quickly into the how-to learning process, cross-referencing the user guides for overviews, concepts, interface descriptions, or reference material as necessary. Important: Adobe is held contractually accountable for what the basic product documentation says about our products. Ideally, tutorials are supplemental to product docs (user guides) and could be removed from Experience League without affecting our contractual obligations. If you create a tutorial and find yourself duplicating user guide information, the content easily becomes outdated and mismanaged. Writing teams should frequently communicate with each other to avoid such duplication, and to keep information separated appropriately.
Course	Adobe expert-curated collection of content, typically comprised of multiple lessons to educate users about a broad area, use case, or product (like implementation, user fundamentals). Courses are developed for target audience roles/role responsibilities. See the Experience League Courses landing to browse courses.
	Knowledge base (KB) articles are ideally brief write-ups with information that is temporarily relevant and useful in specific situations. KB information includes upcoming outages, release issues, product workarounds, or troubleshooting help for these situations. KBs quickly get outdated and aren’t always managed in the publication process (updated and localized). If you author KBs and find yourself documenting standard product functionality as part of the article (steps in a task, for example), you should stop writing and instead cross-reference to the formal documentation. If you can’t find the documentation, notify the writer or product manager for that product.

Conceptual information

Overviews and concepts are not the same content types. In information design, overviews come first. They introduce a product or collection of features and describe what they can help you accomplish. Write an overview for:

• Solution or product.
• Large features that contain (but don’t necessarily require) multiple procedures.

Sample published overview.

Sample overview layout

The following layout shows a sample overview with child sections or topics. Depending on how your authoring tools and on how much information each of these cover, this group could be all on one page, or separate pages:

Fallout reports
 Types of Fallout reports
 How to interpret Fallout reports
 Fallout reports in Report Builder
 Fallout reports in Analysis Workspace

Concepts, sections, and topics

Concepts come after an overview and precede the task. They provide background information (the why) that users must know before they can successfully work with a product (meaning, perform the important task, or the how). A concept might also have an example or a graphic, but generally the structure of a concept is fairly short and simple.

Sample concept preceding a task (on the same page).

Think of topics as discreet enough to be separate pages. (Topic is often called an article, but they mean different things, especially if you also manage a knowledge base separate from product documentation.)

Think of sections as subheadings on the same concept topic/page. A section represents an organizational division in a topic. Sections are used to organize subsets of information that are directly related to the topic. Multiple sections within a single topic do not represent a hierarchy, but rather peer divisions of that topic.

To learn about creating headings, see headings and page titles.

Procedural information

Procedures, or tasks, answer “How do I?” questions. They have a well-defined structure that describes how to complete a procedure to accomplish a specific goal. The task follows the concept.

For a conceptual page with subtasks, use a noun phrase for the title, then imperative verbs for child tasks. Examples:

Symbols (conceptual information about symbols)
 Create a symbol
 Modify a symbol
 Redefine a symbol

What’s in a task

Limit task information to:

• Navigation
• Screens
• Interface elements to click or complete to accomplish the task
• Field/option descriptions
• Use UICONTROL with bold when referring to interface elements in a task. (See Localization for more.)

Authoring standards for a task

• Use sentence style capitalization for a task heading.
• Add conceptual information (including prerequisites), where necessary, before the steps. (Most conceptual information should reside in the overview preceding the task, but some tasks require contextual conceptual information.) If you find yourself adding more than a paragraph of conceptual information before the steps in a task, you likely need to create a concept heading.
• Steps: Use Markdown syntax. A step is a command that contains only one brief command: the step users take. Extra information (step results, images, information about the step) must go on the next line.
• Images: Store graphics (screenshots, process graphics) in the Assets folder in the guide, and link to the asset (using Markdown syntax).

Fields and options

Document the navigation to (and definitions for) interface fields and options in Task (steps) content types. If you find yourself doing this in a concept, overview, FAQ, or anywhere outside of the procedure, the information is in the wrong place. Additionally, use bold UICONTROL for interface elements so that readers can scan for this information. When they find the bold UI element name, everything they need to know about the UI element should be in the definition, or nearby it (in the step).

Sample step with field descriptions: