Document Hub Basics

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

Available in public preview from Alation version 2024.1

Important

You are viewing documentation for Classic Alation.

Overview

Document Hubs help your company organize long-form, written documentation related to your data. With Document Hubs, you can create your own documentation types, such as project documentation, business processes and policies, best practices, metric definitions, help content, or whatever suits your organization. You can create multiple document hubs for different purposes. Each document hub is featured prominently in the catalog navigation, and search results can be filtered based on document hubs.

Structure

Document hubs are made up of documents and folders. Hubs are the top-level containers. Beneath hubs are folders. Folders contain documents. Documents hold your written content.

Manage Documents through Folders

Folders help you manage the documents they contain. You can manage permissions, domains, and workflows on the folder level and enable documents to inherit the folder settings. You can also manage these things on the document level if desired.

Customized Names

Alation administrators can customize the names of these objects for each hub, so you may not see the terms document hub, folder, or document in Alation unless you’re an administrator. The icons associated with these objects can’t be changed, so you can use the icons shown above to tell whether something is a document hub, folder, or document.

Permissions

Folders and documents are visible to everyone by default. Folders and documents can be restricted to certain users. If you don’t have permission to view a folder or document, you won’t be able to see it anywhere in the Alation catalog.

Enable Document Hubs

To get started with Document Hubs, see Enable Document Hubs.

Navigate Document Hubs

All document hubs can be found in the left navigation menu.

1. If the left navigation isn’t visible, click the left navigation icon.

   

2. In the left navigation, document hubs have bookshelf icons and are listed near the bottom in order of their creation date. Click a document hub to open the document hub page on the right.

   

3. The left navigation shows a list of all the folders in the document hub, with an arrow to show or hide the documents in each folder. The pane on the right lists all the document hub’s folders at the top and its documents at the bottom. Click a folder or document name to open it.

All document hubs can be found in the Apps menu. They’re located near the top and have bookshelf icons.Here’s an example showing three document hubs with some custom names:

Click a document hub to open the document hub page. The document hub page lists all the document hub’s folders at the top and its documents at the bottom. Click a folder or document name to open it.

Search Document Hubs

In Alation’s search, you can filter the results to specific document hub content.

To filter search results by document hub content:

1. Click on the search box, then click Search Alation, or enter a search term and click See all results.

2. Expand the Object Type menu on the left.

3. To filter the search results to all document hub content, select Documentation. This will search the contents of all document hubs.

4. To filter to a specific document hub, expand Documentation and select a document hub. This will search all the folders and documents in that hub. You can select multiple hubs.

5. To filter to a specific folder with a document hub, expand the document hub and select the folder. You can select multiple folders.

6. To filter to only documents within a document hub, expand the document hub and select the document type.

1. Click on the search box, then click Search Alation, or enter a search term and click See all results.

2. Click Documentation from the list of filters at the top.

3. Select the document hubs, folders, or document types you’d like to search. Use the search filter at the top of the drop-down menu to filter the list of hubs, folders, and documents.

Create and Configure Document Hubs

You must be a Server Admin or Catalog Admin to create or configure Document Hubs. You must be a Steward or higher to create or configure folders and documents.

Where Are Articles in the New User Experience?

Articles are only visible in the classic user experience. In the New User Experience, you will only see Document Hubs, and any links to articles will take you to the classic user experience.

If you have access to the Alation Community, you can find more information in the Alation Brief recording: Document Hubs: An Update on the Future of Articles.

Document Hubs vs. Articles

Document Hubs are the new documentation feature in Alation. They will eventually replace articles. Alation will provide a migration path from articles to Document Hubs.

Here are some key advantages to Document Hubs:

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 are required to have one and only one template, which provides more consistent layouts. Articles could have multiple templates or no template at all.

• Document Hubs can have a default template.

• Folders have their own templates, while article groups can’t have templates at all.

Workflows

• Folders can be managed with the powerful Workflows feature (requires the Data Governance app), which is more customizable than the simple Agile Approval feature for articles.

General

• Document Hubs can have customized names, allowing you to meet specific uses for your business.

• Document Hubs are faster, more reliable, and more scalable than articles.

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 Document Hubs are enabled, future enhancements to Document Hubs will automatically apply to glossaries and terms.

Roadmap

Included in Public Preview I:

• Define document hubs in Classic or New User experience (admin roles only)

• Publish document hubs for non-admin users

• Create folder and document pages

• Define workflows

• Public APIs

On the roadmap:

• Improvements to Document Hubs integration with Alation Analytics

• Relevant Documents (backreference with @-mentioning of documents)

• Breadcrumbs in document selection dialog

• Deletion of empty document hubs

• Document preview on the Alation homepage

• Taxonomy

• Stewardship Workbench

• Migration solution

Deprecation and Migration of Articles

Alation will provide a migration path from articles to Document Hubs. 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.

• 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.

• 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).

Providing Feedback on the Public Preview

Please use the Alation Customer Ideas Portal to submit your feedback on Document Hubs.

Select Document Hubs under Previews as your category when creating a new idea.

The Alation team will review and provide feedback to improve the experience. All statuses will adopt their standard meaning except:

• On the Roadmap means we will plan to address within the General Availability timeframe or as a fast follow.

• Future Consideration means we will consider in the future but it will not be part of General Availability.

• If a suggestion is not under consideration for this initiative but may be for another initiative, the idea will be moved into a different category.

• If a suggestion will not be considered across any category, it will be listed as Not Under Consideration.

Frequently Asked Questions (FAQ)

1. What happens to glossaries and terms?

   Glossary and Terms will continue to function as is. When the Document Hubs 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.

2. What happens to articles?

   There is no impact to articles currently, but we are aiming to deprecate articles after we have validated Document Hubs and ensured all customers have a path forward in migrating articles to Document Hubs successfully.

3. 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.

4. What will the articles migration path look like?

   We are currently working on defining an improved migration experience that may not involve Bulk Utility. We will share more information on migration in the coming months.

5. What will happen to attachments in articles during migration?

   We understand this is a migration concern for some customers. We are investigating how we can help these customers move from uploaded content to attachment links in Document Hubs.

6. 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.

7. Will Bulk Utility be available to bulk load glossary terms and Document Hubs?

   Bulk Utility will continue to be available for terms until we have solidified the bulk upload method for Document Hubs.

8. 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.

9. Will the Alation homepage support object preview of Documents?

   We will be adding support for this feature.

10. 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.

11. What are the 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)	Object Sets in public preview I, Relevant Documents will be in public preview II
    Version history	Yes	Yes, advanced history with field level changes
    Domains	Limited	Yes
    Permissions	Yes	Yes
    Bulk permissions	No	Yes
    Workflow	Limited - Agile Approval	Change management; add new object
    Children	Yes	Will be available in public preview III
    Attachments	Yes	No