Document Hub Basics¶
Alation Cloud Service Applies to Alation Cloud Service instances of Alation
Customer Managed Applies to customer-managed instances of Alation
In General Availability from Alation version 2024.3.2
In Public Preview from Alation version 2024.1 to 2024.3.1
Important
You are viewing documentation for Classic Alation.
Document Hubs are Alation’s new feature set for creating custom types of documentation. Included within Document Hubs is the Glossary Hub, which is the default hub for managing business term definitions.
Document Hubs will eventually replace articles. Until you are fully ready to transition to Document Hubs, articles remain in the catalog. However, articles are only visible in the classic user experience. Document Hubs are available in both the new user experience and the classic user experience.
Where Are Articles?¶
When you’re in the new user experience, articles are not findable through the main menu. You can use Alation’s search to find them. All links to articles will open the article in the classic experience.
When you’re in the classic user experience, find articles through the left-side navigation and search.
Note
We consider migrating existing Articles to the Document Hubs landscape as mission-critical. To support this, 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.
Document Hub Overview¶
With Document Hubs, you can create your own documentation types, such as glossary terms, 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.
Document Hubs come with a built-in, customizable Glossary Hub for your business term definitions. If you’ve already been using the existing Glossaries and Terms feature, it will automatically become part of Document Hubs. See the Documentation topic for more information about the relationship between Document Hubs and Glossaries and Terms.
Each document hub is featured prominently in the catalog navigation, and search results can be filtered based on document hubs.
The primary features of document hubs are described below:
For administrators:
Document Hub Basics¶
Hierarchical Structure¶
In 2024.3.2 and newer, you can nest folders and documents in Document Hubs. Folders can have subfolders, and documents can have subdocuments. A folder can contain both documents and subfolders.
A document must have a single parent folder. Documents can inherit permissions, domains, and workflows from their parent folder only. Documents may also have navigation links to other folders within a document hub.
The top level of the document hub itself can also contain documents directly, although this is discouraged as it makes the documents less discoverable and prevents them from inheriting permissions, domains, and workflows from a parent folder.
In 2024.1 to 2024.3.1, Document Hubs had a simple three-layer structure:
Hubs are the top-level containers. Document hubs are made up of documents and folders.
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 generic terms document hub, folder, or document in Alation unless you’re an administrator. However, you may see the generic terms in certain cases, like when the administrator hasn’t customized the names or when document hub objects are referred to outside the context of a specific hub.
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, but they can be restricted to certain users if needed. 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. See Document Hub Permissions for more details.
Mentions¶
Like other catalog objects, documents and folders can be @-mentioned in text fields throughout the catalog, enabling you to link to relevant documentation.
You can also @-mention other catalog objects within the description or other rich text fields in documents and folders. Starting in 2024.1.3, when a catalog object’s template includes the Mentions field, all documents and folders that @-mention the object will be listed. This makes it easier to find relevant information.
Navigate Document Hubs¶
All document hubs can be found in the left navigation menu.
If the left navigation isn’t visible, click the left navigation icon.
In the left navigation, document hubs have bookshelf icons and are listed near the bottom in order of their creation date.
Click the arrow next to a document hub to see its contents in the left navigation. 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. In 2024.3.2 and newer, you can use the arrows to navigate down to subfolders and subdocuments. Click Show <Documents> if needed to see all the documents in a folder (the actual name of the link depends on the customized name that admins have chosen to call documents in a particular hub).
Click the name of a document hub to open the document hub page on the right. The document hub page on the right lists all the document hub’s folders at the top and its documents at the bottom. Click a folder or document title 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 title to open it.
In 2024.3.2 and newer, catalog pages for folder and document may show subfolders or subdocuments:
A folder catalog page displays a list of its subfolders at the top and its documents at the bottom. If there are no subfolders, only the folder’s documents are shown. An admin can move the location of these lists up or down in the hub’s folder template.
A document catalog page shows a list of its subdocuments in the Sub-<Documents> field (the actual name depends on the customized name that admins have chosen to call documents in a particular hub). By default, the subdocument field appears in the right sidebar. An admin can customize the location of this field in the document’s template or choose to remove it completely.
Navigation Links¶
You can add navigation links to multiple folders, enabling better findability and indicating that a document may be related to more than one folder. A linked document is listed on the linked folder’s catalog page with a link icon next to its name.
Navigation links are shown on the linked document’s catalog page in the Properties field.
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:
Click on the search box, then click Search Alation, or enter a search term and click See all results.
Expand the Object Type menu on the left.
To filter the search results to all document hub content, select the checkbox next to Documentation. This will search the contents of all document hubs.
To filter to a specific document hub, click the arrow next to Documentation and select the checkbox next to a specific document hub. This will search all the folders and documents in that hub. You can select multiple hubs.
To filter to just folders or documents within a given hub, click the arrow next to a document hub and select the checkbox next to Folders or Documents for that hub. You can make multiple selections.
Click on the search box, then click Search Alation, or enter a search term and click See all results.
Click Documentation from the list of filters at the top.
To filter the search to specific document hubs or to just folders or documents within a given hub, select the corresponding checkboxes. You can make multiple selections.
To filter to just the contents of a specific folder or to documents based on a given template, click the See [#] More Filters button in the Filters panel on the left. The left panel expands. Scroll to find the folder or template you want to filter to and select the checkbox next to it.
Adjust the Document Hub Table View¶
Document hub pages contain tables showing the folders and documents in the hub. Folder pages contain a table of documents (and subfolders, in 2024.3.2 and newer) in the folder. Admin users determine the default view for these tables, but individual users can temporarily adjust the view as needed.
Search¶
At the top of each document or folder table is a search box. Enter a search term in the search box. The list of documents or folders will be filtered to show those that match the search term. The search will look for matches on the title, description, and custom field values.
Sort¶
By default, items in a document or folder table are sorted alphabetically by title. You can reverse the sort order by clicking the title header.
Add, Remove, and Rearrange Columns¶
Starting in 2024.1.3, you can add, remove, and rearrange the columns in a document or folder table. To do this, click the column icon next to the search box.
The Column Organization menu opens. It contains a list of all the custom and built-in fields in the available templates.
If the list of available columns is long, use the search box at the top of the menu to find the column you’re looking for.
To add a column, select the corresponding checkbox in the list. To add all available columns, select the checkbox at the top of the list.
To remove a column, clear the corresponding checkbox in the list. The title column can’t be removed. To remove all available columns, clear the checkbox at the top of the list (it can’t be completely cleared, since the title column can’t be removed).
To change the order of the columns in the table, hover over the column name in the Column Organization menu and drag it to a new place in the list.
To return the column organization back to its default settings, click Reset.
To finish adjusting the column settings, click away from the Column Organization menu.
Enable Document Hubs¶
For help enabling Document Hubs, see Enable Document Hubs.
Create and Configure Document Hubs¶
For more about creating and configuring Document Hubs, see Manage Document Hubs.