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.
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. |
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:
Although overviews come first, you should write them last. Only after you finish documenting the product do you understand it well enough to write the 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 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.
Procedures, or tasks, answer “How do I?” questions. See Steps and lists for details.
This document describes the different types of content and documentation (hat tip to the Experience Platform content team).
For information about the documentation process, see Experience Platform Content and Documentation process overview (wiki).
To request interface content or documentation, see JIRA Documentation Tickets (wiki).
Content type | Audience | Description |
---|---|---|
Contextual popovers and tool tips | Product users | Contextual guidance to help users understand UI elements and workflows. See How to add contextual help popovers to the Experience Platform documentation and UI (wiki). |
Error messages and other in-product messages | Product users | Error messages (wiki), status messages, and other messages that might appear during product usage. |
Gainsight engagement strings | Product users | Information about new features and other highlighted product elements using the Gainsight (wiki) software. |
UI strings | Product users | Text that appears in the user interface, such as descriptions, options, controls, fields, and so on. |
Documentation type | Audience | Description | Example |
---|---|---|---|
API guide | Developers | Complete information about how to develop for a product or features, primarily using the APIs. | Batch Ingestion API guide |
API reference | Developers | Information about properties, parameters, and other API components. | Access Control API |
Conceptual overviews | All users | Information about product and feature concepts, including a general description of the product or feature, the problems it solves, and how it can help users achieve their goals. | Data collection overview |
How-to | All users | How to accomplish a specific task using a product or feature. | Create a rule |
Integration guide | All users | Information to help integrate multiple products or features. | Configure personalization destinations for same-page and next-page personalization |
Release notes | Administrators and other users | Information about the most recent release, including new features, bug fixes, and known issues. | Adobe Experience Platform release notes |
Troubleshooting guide | All users | How to resolve issues that might occur during the normal usage of a product or feature. Includes common issues, error codes and their meanings, and other details to help identify and resolve problems. | XDM System troubleshooting guide |
Tutorial | All users | How to achieve a specific goal using a series of products or features, usually containing a sample use case or scenario and examples specific to that use case. | Importing and using external audiences |
Use cases | All users | Details about a specific use of the product or feature, including examples specific to the audience for that use case. Use cases can span multiple features and products. Use cases should be aligned across Docs, Blueprints, Tech Mktg materials. | Example Use Case for Real-time Customer Data Platform B2B Edition |
User guide | End users | Complete information about how to use a product or features, primarily using the user interface. | Sandbox UI guide |