Roadmap - Shutdown Docs AE Glossary #6111

JKarlavige · 2024-09-20T20:00:51Z

What are you changing in this pull request and why?

We are moving 10 key terms from the Docs glossary over to the WWW blog. The goal is to maintain the hover snippet functionality where the Term component is used throughout the site, while shutting down the individual term pages.

The terms we are migrating vs. what we are redirecting to the blog index can be found here. This defines what redirects point to specific WWW blog pages vs. what falls under the wildcard redirect pointing to the blog index.

This PR:

Removes the glossary index page and all term pages
Moves all existing terms into single docs/terms.md file to maintain hoverSnippet functionality using Term component
Refactors Term component to remove linking to individual pages

Documentation

Our documentation on terms/hover snippets have been updated: https://www.notion.so/dbtlabs/How-to-use-Docusaurus-glossary-terms-hover-snippets-dc5cc7bfc05848fd8ea3906239da97da?pvs=4

Previews

Verify hover snippets show correctly on test page:
https://docs-getdbt-com-git-roadmap-ae-glossary-dbt-labs.vercel.app/docs/test-terms

Verify hover snippet works on prod pages where Term component is used:

ELT & ETL term pages should remain live as part of this initial update. They will be migrated to the WWW blog at a later date:

TODO Before Merge

Merge WWW PR 313
Migrate terms to WWW blog
Remove test-terms.md page
Remove test terms from hover-terms.md

vercel · 2024-09-20T20:00:54Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
docs-getdbt-com	✅ Ready (Inspect)	Visit Preview	Oct 2, 2024 1:37pm

JKarlavige · 2024-09-20T20:01:09Z

website/docs/docs/test-terms.md

delete before merge

JKarlavige · 2024-09-20T20:29:44Z

website/docusaurus.config.js

@@ -246,6 +242,9 @@ var siteSettings = {
          //showLastUpdateAuthor: false,

          sidebarCollapsible: true,
+          exclude: [
+            'hover-terms.md'


Prevents hover-terms page from being built on the site. This file is only used for storing hover snippets which are used in the custom Term component.

john-rock

lgtm. Confirmed snippet appears to be working correctly and redirects are also working as expected.

Just curious, I'm assuming the ones on the sheet that are marked Need to consolidate will be merged into a single WWW blog post?

runleonarun

Hey @JKarlavige This looks great! I just had a few questions. Thanks for getting this PR up 🙇🏻‍♀️

runleonarun · 2024-09-25T16:48:08Z

website/docs/terms/hover-terms.md

+  hoverSnippet: Data lineage provides a holistic view of how data moves through an organization, where it’s transformed and consumed.
+
+data-warehouse:
+  displayText: data warehouse


@JKarlavige It looks like we lost the links to https://docs.getdbt.com/docs/environments-in-dbt and https://docs.getdbt.com/terms/view on the about environments page. Will links and terms no longer be compatible?

Does this refer to the links when clicking the terms themselves on a page? If so - yes, these hover snippets will no longer be linkable, only the hover snippet functionality remains in place.

If term URLs are hit directly, they will either redirect to the migrated WWW blog page if that term was migrated, or redirected to the WWW blog index if that term wasn't migrated.

I did update two files where we were linking to term pages as Docusaurus was flagging them as broken links. But even if any links are still out there, they will redirect rather than 404ing when hit

runleonarun · 2024-09-25T18:30:12Z

website/docs/docs/test-terms.md

+
+This has displayText set but no hoverSnippet set: <Term id="noHoverSnippet" />
+
+This should NOT show a hover snippet (but should still show children): <Term id="demo">Demo</Term>


Hey @JKarlavige This looks correct, but not sure what you mean by it should still show children?

Good question! If the Term component is used but the id isn't found in hover-terms.md, it would still show the children of the component, in this case the text Demo. These are just some test cases i added for us to test when reviewing the PR. But i will remove all of these before merge.

runleonarun · 2024-09-25T18:37:10Z

website/docs/terms/hover-terms.md

+  hoverSnippet: This is a demo term hover snippet
+  displayText: Yay demo term
+
+noDisplayText:


Not sure of the use case here. Also it seems to not be working on the test page, but likely it's that I'm not understanding what it should be doing 😆

Yeah feel free to disregard these ones 😅 i just wanted to add some test cases for us to review to ensure the pages won't break in certain scenarios. The noDisplayText example falls back to displaying the id text itself ("noDisplayText") on the page, if both the displayText property and children are missing.

Here's an actual use case on this functionality, say we had a term snowflake in the hover-terms.md file:

snowflake: hoverSnippet: This is the hover snippet text when hovering over the Snowflake term

Then the Term component is used like this on a page: <Term id="snowflake" />

Since it doesn't have a displayText property set in hover-terms.md, and child text isn't passed into the component (for example: <Term id="snowflake">this is child text</Term>), it will fallback to showing the id on the page instead, which is snowflake.

Ah! Thanks for the explanation!

runleonarun · 2024-09-25T18:38:22Z

website/docs/terms/hover-terms.md

+noDisplayText:
+  hoverSnippet: No Display Text hover snip
+
+noHoverSnippet:


What's the use case for noHoverSnippet?

This example shows how a term will appear on a page if a term is set in hover-terms.md, but the hoverSnippet property isn't set for that term. So if the Term component is used on a page: <Term id="noHoverSnippet" />, and this term doesn't have a hoverSnippet set, it will just display plain text on the page with no hover snippet functionality

JKarlavige · 2024-09-26T14:57:15Z

@runleonarun One other update - we have 3 terms that the SEO agency is helping consolidate into one to migrate to the WWW blog, they are:

Rather than pausing the project while waiting on those pages to be consolidated into one blog post, we will leave those 3 term pages live for now on docs. Then once a new blog post is together and published, we will go back and shutdown these final 3 term pages.

… post

runleonarun

Thanks for the explanations JK! Approving.

JKarlavige added 9 commits September 20, 2024 15:30

refactor Term component to pull from single file

6109056

migrate terms to single terms.md file

5cf4e1d

exclude docs in terms directory from building pages

60d5799

remove glossary sidebar section

9259ae8

remove glossary nav link

3cc57a2

remove term pages and directory and relocate terms.md file

992a933

update demo test-terms page

0b8fce0

remove link component from term component

46c23a5

adjust pageReady handling in terms component

7034b34

github-actions bot added content Improvements or additions to content size: large This change will more than a week to address and might require more than one person labels Sep 20, 2024

JKarlavige commented Sep 20, 2024

View reviewed changes

website/docs/docs/test-terms.md Outdated

Copy link

Collaborator Author

JKarlavige Sep 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

delete before merge

vercel bot had a problem deploying to Preview September 20, 2024 20:03 Failure

JKarlavige added 3 commits September 20, 2024 16:12

update name of hover-terms file

06f2c75

update comment

238844f

update term links on two pages

575c176

vercel bot had a problem deploying to Preview September 20, 2024 20:29 Failure

JKarlavige commented Sep 20, 2024

View reviewed changes

move hover-terms into terms directory to suppress partial warning

115d50f

vercel bot deployed to Preview September 23, 2024 14:09 View deployment

JKarlavige added 2 commits September 23, 2024 10:18

fix text color when term used in callout

a4aa9b6

revert pageReady edits to Term component

769ca87

vercel bot deployed to Preview September 23, 2024 14:26 View deployment

JKarlavige added 3 commits September 23, 2024 10:32

only use ReactTooltip if hoverSnippet set

93288c9

add redirects

d8e8999

Merge branch 'current' into roadmap/ae-glossary

41a1197

JKarlavige marked this pull request as ready for review September 23, 2024 14:44

JKarlavige requested a review from a team as a code owner September 23, 2024 14:44

vercel bot deployed to Preview September 23, 2024 14:48 View deployment

Merge branch 'current' into roadmap/ae-glossary

72ad8e2

vercel bot deployed to Preview September 24, 2024 08:56 View deployment

JKarlavige requested review from breezyfasano and john-rock September 24, 2024 19:06

update data-grain redirect

b5e9a92

vercel bot deployed to Preview September 24, 2024 20:02 View deployment

merge current

12dfa05

vercel bot deployed to Preview September 24, 2024 20:41 View deployment

john-rock approved these changes Sep 25, 2024

View reviewed changes

runleonarun reviewed Sep 25, 2024

View reviewed changes

JKarlavige added 2 commits September 26, 2024 10:57

Merge branch 'current' into roadmap/ae-glossary

fd0b898

bring back 3 etl pages so these remain live while working on new blog…

4ec0649

… post

vercel bot deployed to Preview September 26, 2024 15:05 View deployment

remove test terms and test page

33bdcc3

vercel bot deployed to Preview September 26, 2024 16:53 View deployment

runleonarun approved these changes Sep 26, 2024

View reviewed changes

Merge branch 'current' into roadmap/ae-glossary

3ea1881

vercel bot deployed to Preview October 2, 2024 13:37 View deployment

JKarlavige merged commit ea02592 into current Oct 2, 2024
6 checks passed

JKarlavige deleted the roadmap/ae-glossary branch October 2, 2024 13:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Roadmap - Shutdown Docs AE Glossary #6111

Roadmap - Shutdown Docs AE Glossary #6111

JKarlavige commented Sep 20, 2024 •

edited

Loading

vercel bot commented Sep 20, 2024 •

edited

Loading

JKarlavige Sep 20, 2024

JKarlavige Sep 20, 2024

john-rock left a comment •

edited

Loading

runleonarun left a comment

runleonarun Sep 25, 2024

JKarlavige Sep 26, 2024

runleonarun Sep 25, 2024

JKarlavige Sep 26, 2024

runleonarun Sep 25, 2024

JKarlavige Sep 26, 2024 •

edited

Loading

runleonarun Sep 26, 2024

runleonarun Sep 25, 2024

JKarlavige Sep 26, 2024

JKarlavige commented Sep 26, 2024

runleonarun left a comment


		This has displayText set but no hoverSnippet set: <Term id="noHoverSnippet" />

		This should NOT show a hover snippet (but should still show children): <Term id="demo">Demo</Term>

Roadmap - Shutdown Docs AE Glossary #6111

Roadmap - Shutdown Docs AE Glossary #6111

Conversation

JKarlavige commented Sep 20, 2024 • edited Loading

What are you changing in this pull request and why?

Documentation

Previews

TODO Before Merge

vercel bot commented Sep 20, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

john-rock left a comment • edited Loading

Choose a reason for hiding this comment

runleonarun left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JKarlavige Sep 26, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JKarlavige commented Sep 26, 2024

runleonarun left a comment

Choose a reason for hiding this comment

JKarlavige commented Sep 20, 2024 •

edited

Loading

vercel bot commented Sep 20, 2024 •

edited

Loading

john-rock left a comment •

edited

Loading

JKarlavige Sep 26, 2024 •

edited

Loading