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¶
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 to articles, Alation will provide a migration path from articles to Document Hubs, as explained below.
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¶
Articles will be deprecated once we’ve validated Document Hubs and ensured all customers have a path forward in migrating articles to Document Hubs successfully.
We consider migrating existing Articles to the Document Hubs landscape as mission-critical. There are three possible migration paths to Document Hubs:
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. The in-product migration solution will be rolled out gradually, starting with a tightly managed pilot involving a few customers in 2024.3.2, and becoming generally available soon after.
This migration path may be a good option if:
You can wait until the solution is available
The migration paths described below won’t work for you
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 want to use Document Hubs for new content
You have expertise in using APIs
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.
This migration path may be a good option if:
You want to start using Document Hubs right away
You are satisfied with all your article content being part of the built-in Glossary Hub until Alation provides a way to move content to different document hubs
You want a user interface rather than APIs to perform the migration
Effect of Migration on Other Features¶
When you migrate to Document Hubs, some features you may have used with articles will be limited or won’t work with Document Hubs:
Agile Approval. Use Workflows instead (requires Data Governance app).
Article references. During migration, references to articles via @-mentions or object sets will be replaced with references to the migrated document, unless you migrate using APIs.
Attachments. Since Document Hubs don’t support attachments, we are investigating how to help you move from uploaded file attachments to attachment links in Document Hubs.
Bulk Utility. Will continue to work with terms only.
Suggested Terms (Lexicon). This feature doesn’t work with Document Hubs.
Frequently Asked Questions (FAQ)¶
Here are answers to some frequently asked questions about the transition to Document Hubs:
What happens to glossaries and terms?
Glossary and Terms will continue to function as is. When the Document Hubs 3 feature flag is enabled, Glossary will become a type of Document Hub. So any enhancements to Document Hubs will be reflected in Glossary and Terms.
What happens to articles?
There is no impact to articles currently, but we are aiming to deprecate articles in September 2025 ensured all customers have a path forward in migrating articles to Document Hubs successfully.
Will we have to pay for the Data Governance app now when we are used to Agile Approval for articles free of cost?
We understand this is a friction point for current article users and are looking to see how best we can address this issue.
What will the articles migration path look like?
We have developed an in-product migration solution and additional resources for customers to self-serve at their own pace. The in-product migration solution will be rolled out gradually, starting with a tightly managed pilot involving a few customers in 2024.3.2, and becoming generally available soon after. In the meantime, there are two alternate paths to migrate articles to Document Hubs. See Migration and Deprecation of Articles.
What will happen to attachments in articles during migration?
Attachments will continue to be available in migrated Documents until Articles are deprecated in September 2025. Users can download or delete Attachments but cannot upload new Attachments.
What will happen to existing @-mentions or references to articles after migration?
@-mention of articles and existing references of articles in object sets will be replaced with a migrated document page reference, as it works with terms migration today. The exception is if you migrate using the public APIs, in which case you’ll have to recreate the @-mention manually.
Will Bulk Utility be available to bulk load glossary terms and Document Hubs?
We are looking to converge with other bulk update methods such as Data Dictionary for Document Hubs. The Bulk Utility will continue to serve Glossary and Terms until the alternate method has materialized.
What about migrating a glossary folder to a different Document Hub?
Moving a folder to a different Document Hub is currently targeted for early 2025.