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:
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.
Glossaries and Terms were introduced in Alation version 2022.2 as a dedicated solution for documenting business and technical terms related to your data. For help with glossaries and terms, see Glossaries and Terms. Glossaries and Terms are included within Document Hubs.
Document Hubs is Alation’s new documentation solution, introduced in public preview in Alation version 2024.1. For help with Document Hubs, see Document Hubs.
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 Glossaries or Document Hubs 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 extend and build on 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 |
Additional context |
No |
Yes, template name and breadcrumbs will show up in search results |
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 |
Coming soon: Enhanced hierarchy relationships with nested folders and sub-documents will be available with Document Hubs 1.0 |
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 expect to have a fully-featured migration solution available near the end of 2024 and articles to be fully deprecated near the end of 2025.
There are three possible migration paths to Document Hubs:
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
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 Document Hubs with the Upcoming UI¶
Alation is preparing a method for migrating that will provide a dedicated user interface, which will be available in a future release. With this upcoming method, article references would automatically be converted into corresponding document references.
This migration path may be a good option if:
You can wait until the solution is available
The migration paths described above won’t work for you
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 the second half of 2025 after we have validated Document Hubs and 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 are currently working on a user experience that will involve migrating Article Groups to a new or existing folder in an existing Document Hub. More information to come. 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?
While attachments as a property will not exist, we are looking for ways to provide the attachment URL in the document description or banner, allowing for customers to replace this attachment with an external reference field.
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?
Migrating articles will be first priority, followed by migrating terms, glossaries, and business policies to other Document Hubs, in that order.
How do I choose between articles, terms, and Document Hubs?
Choose Glossary Terms or Document Hubs 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 entrypoints in the UI for Articles and Article Groups.