Documentation¶

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

Alation’s documentation features enable you to create written content related to your data. For example, you can define glossary terms, document governance policies and best practices, record metrics and KPIs, and write other text content relevant to your data.

Alation has three documentation feature variants:

Document Hubs is Alation’s new documentation solution, in General Availability as of release 2024.3.2. Document Hubs includes a built-in Glossary Terms hub. For help with Document Hubs, see Document Hubs.
Glossaries and Terms were introduced in Alation version 2022.2 as a dedicated solution for documenting business and technical terms related to your data. Glossaries and Terms are included within Document Hubs. For help with glossaries and terms when you haven’t enabled Document Hubs, see Glossaries and Terms.
Articles are Alation’s original documentation feature. We are in the process of replacing articles with Document Hubs. Articles are not available in the New User Experience. For help with articles, see Articles.

Document Hubs includes the existing Glossaries and Terms feature and replaces the Articles feature. This is explained in more detail below.

Choosing between Articles, Glossaries, and Document Hubs
Document Hubs vs. Glossaries
Document Hubs vs. Articles
Migration and Deprecation of Articles
Frequently Asked Questions (FAQ)

Choosing between Articles, Glossaries, and Document Hubs¶

We recommend using Document Hubs or Glossaries where it meets your needs, so that you minimize migration effort down the road.

If you are not using or creating articles, you should be able to turn articles off in the UI so your users are not confused. Server Admins can use the Feature Configuration page to enable the feature flag Hide all entry points in the UI for Articles and Article Groups.

Document Hubs vs. Glossaries¶

Document Hubs build on and extend the existing functionality for Glossaries and Terms. When you enable Document Hubs, there will be no functional changes to your existing glossaries and terms. The Glossary Hub is already considered a document hub, glossaries are considered to be folders, and terms are considered to be documents.

Once you enable Document Hubs, future enhancements will automatically apply across all hubs, including the Glossary Hub.

Document Hubs vs. Articles¶

Document Hubs are the new documentation feature in Alation. They will eventually replace articles. Document Hubs bring a number of important advantages over articles. To facilitate the transition from articles to Document Hubs, Alation has provided a way to migrate articles to Document Hubs. See Migrate Articles to Document Hubs for more information.

Advantages of Document Hubs¶

Document Hubs aims to elevate the Documentation feature set with enhanced customization and an improved search and discovery experience such that you can organize documentation content as it makes sense for your organization. Here is a comparison on some key functionalities.

Functionality	Articles	Document Hubs/Glossary Terms
Custom fields	Yes	Yes, in parity with Glossary Terms
Custom labels	No	Yes, custom labels for top-level navigation, folder, and document names
Layout customization for document/article pages	No	Yes
Layout customization for folder/article group pages	No	Yes, one folder layout per document hub
Template name and breadcrumbs in search results	No	Yes
Relevant content back reference	Yes (Relevant Articles)	Yes (Mentions)
Version history	Yes	Yes, advanced history with field level changes
Domains	Limited	Yes
Permissions	Yes	Yes
Bulk permissions	No	Yes, on the folder level
Workflow	Limited - Agile Approval	Yes, customizable workflows for requesting changes and adding new objects (requires Data Governance app)
Children (taxonomy or hierarchy)	Yes	Yes, nested folders and subdocuments
Attachments	Yes	No

In addition to the items in the table above, Document Hubs offer the following advantages:

Folder-based Stewardship¶

Folders have layout-enabled templates, so you can assign stewards and people sets on the folder level.
You can manage permissions and domains on the folder level and enable documents to inherit the folder settings.
Documents are explicitly assigned to folders, making the association completely user-determined rather than determined indirectly by template assignments.

Template Management¶

Documents can only have one template, which provides more consistent layouts. Articles could have multiple templates, leading to inconsistency in layout.
Document Hubs can have a default template.

General¶

Document Hubs are faster, more reliable, and more scalable than articles.
Document Hubs have extensive public API support with dedicated APIs for both documents and folders.

Migration and Deprecation of Articles¶

We are aiming to sunset articles in September 2025. You can begin migrating articles to Document Hubs now. There are three possible migration paths to Document Hubs:

Migrate to Document Hubs using the dedicated in-product UI
Migrate to Document Hubs using APIs
Migrate to terms using the Bulk Utility

Migrate to Document Hubs Using the Dedicated In-Product UI¶

We have developed an in-product migration solution and additional resources for customers to self-serve at their own pace. This is our recommended solution. See Migrate Articles to Document Hubs for more information.

Migrate to Document Hubs Using APIs¶

With this option, you will use the Documents API and Folders API (available starting in 2024.1.3) to recreate articles as documents. When you use this option, references to articles in the catalog (@-mentions or object sets) will have to be manually replaced with references to the corresponding document.

This migration path may be a good option if:

You have expertise in using APIs
You are willing to engineer your own migration solution
You are willing to manually update former article references to document references

Migrate to Terms Using the Bulk Utility¶

With this option, you will use the Bulk Utility to migrate your articles to glossary terms. Then when you enable Document Hubs, your glossary terms will automatically become part of Document Hubs. In a future release, Alation will provide a way for you to move your content to a different document hub if desired.