Normalizing Network Like A Hyperscaler Course 1 Modules

Hey guys! Today, we're diving deep into the process of normalizing the "Network Like a Hyperscaler – Course 1" modules. This is crucial for getting the content into our standard authoring pipeline, so we can publish it on HubDB and make it available on /learn. Think of it as organizing your digital workspace to make everything accessible and easy to find. Let's break down the current state, the tasks involved, and how we'll ensure everything runs smoothly.

Current State: The Lay of the Land

Currently, we've got four long-form markdown files sitting in content/pathways/network-like-hyperscaler/course-1-foundations/. These cover modules 1.1 through 1.4. The issue? They're missing the required front matter and module folder structure. Imagine dropping a bunch of puzzle pieces onto a table without the box – that's where we are right now. Our pathways ingestion process only scans JSON descriptors, so these markdown files are essentially invisible to our npm run sync:pathways and sync:content scripts as they are. It’s like having a secret stash of knowledge that nobody knows about!

Furthermore, each file links to relative resources like ../../../network-like-hyperscaler/research/CRD_REFERENCE.md. These resources don't exist in the repository, which is a bit like sending someone on a treasure hunt with a map that leads to nowhere. For example, if you look at module-1.1-welcome.md (lines 519-521) and module-1.3-mastering-interfaces.md (lines 1179-1182), you’ll see what I mean. To top it off, there’s no course JSON (content/courses/*.json) or pathway JSON entry referencing these modules. So, even if we normalize them, there’s nothing to tie them all together. It’s like having all the ingredients for a cake but no recipe to follow!

Tasks: Our Action Plan

So, what's the game plan? We've got a series of tasks to tackle to get these modules up to snuff. Think of this as our checklist for digital organization.

1. Module Creation and Migration

For each module (1.1–1.4), we need to create a content/modules/<slug>/README.md file. This file should follow the docs/templates/module-README-template.md template, which includes front matter, learning objectives, and scenario sections. We'll use descriptive slugs like network-like-hyperscaler-welcome and network-like-hyperscaler-how-it-works. The goal here is to migrate the existing body copy into this structured template. It's like giving each module its own dedicated space in our library.

2. Capturing Metadata

Next up, we need to capture prerequisites, learning objectives, and other key metadata in the front matter. This is like labeling our books with all the important details. We’ll set estimated_minutes to the durations specified in the drafts (15, 15, 15, 10) and tag them appropriately, perhaps under [fabric-operations, hyperscaler, network-operations]. If we need more detailed prerequisites or objectives, we can add optional meta.json files. This step ensures that our modules are easily searchable and understandable.

3. Link Management

We’ve got to deal with those broken relative links that point to ../../../network-like-hyperscaler/**. We have a couple of options here: either author the referenced docs under docs/network-like-hyperscaler/** and update the links, or convert them to external URLs or inline explanations. The key is to ensure the markdown renders cleanly. Think of it as making sure all the roads on our map actually lead somewhere!

4. Course Descriptor Creation

Once the modules are in place, we'll add a new course descriptor at content/courses/network-like-hyperscaler-foundations.json. This will include the four module slugs in order, a short summary, the total estimated minutes, and relevant tags. It’s like creating a table of contents for our course.

5. Pathway Descriptor Creation

We also need a matching pathway descriptor at content/pathways/network-like-hyperscaler.json. This will point to the new course via the courses array and include a marketing summary, display order, tags, and a social image (if we have one). This step is crucial for making the course discoverable on our platform.

6. Cleanup

After migrating the content, we'll remove the legacy content/pathways/network-like-hyperscaler/course-1-foundations/ directory. We want to keep the repository clean and organized, so we'll only keep JSON files inside content/pathways/. It’s like decluttering your workspace after a big project.

7. HubDB Sync

Time to run the HubDB syncs with the new content! We’ll use npm run sync:content, npm run sync:courses, and npm run sync:pathways. Don't forget to save the console output to verification-output/network-like-hyperscaler-course-1-sync.txt for auditing purposes. This is like publishing our work to the world!

8. Smoke Testing

We'll smoke-test /learn/catalog, /learn/modules/<slug>, /learn/courses/network-like-hyperscaler-foundations, and /learn/pathways/network-like-hyperscaler to make sure the new entries render correctly from end to end. We’ll also grab a screenshot (desktop) for the pathway or course list and drop it under screenshots/issue-182/ with a short .txt log. This step ensures that everything looks and works as expected.

9. Documentation

Finally, we’ll document the new course in docs/course-authoring.md (Course inventory section) so future authors know the pathway structure. It’s like adding a new chapter to our content creation guide.

Acceptance Criteria: How We'll Know We've Succeeded

So, how will we know when we’ve nailed it? Here are our acceptance criteria:

• All four modules exist under content/modules/**/README.md with valid front matter, linted against the authoring standard, and no orphaned files remain under content/pathways/network-like-hyperscaler/.
• New course and pathway JSON entries compile without type errors and appear in HubDB after running the sync scripts (logs checked into verification-output/).
• Navigating the live site (staging/prod) shows the new course/pathway in the Catalog, and each module renders with objectives, prerequisites, and working links.
• The issue includes links to the verification artifact, screenshot, and any supporting docs that replaced the broken relative links.

Notes: Key Resources and Considerations

Remember to reference docs/content-standard.md, docs/course-authoring.md, and docs/content-sync.md for required fields and workflow. These are our bibles for content creation!

If HubDB rate limits become an issue, just rerun the sync script after the built-in backoff completes; don't comment out retries. We want to play nice with the system.

In summary, normalizing the Network Like a Hyperscaler Course 1 modules is a multi-step process, but each task is crucial for ensuring our content is well-organized, accessible, and valuable. By following these steps, we'll transform raw markdown files into a fully integrated learning experience on our platform. Let's get to work!