Article Validation and Course Maintenance

The course is entirely article-based. Tooling should protect the accuracy and navigability of the writing without turning the repository into a lesson application or exercise harness.

The curriculum is defined in CURRICULUM.md, and the writing approach is defined in ARTICLE_GUIDE.md.

Keep infrastructure proportional

Articles are Markdown files with examples embedded in code fences. They do not need sibling source directories, starter projects, per-article tests, progress metadata, or a build step merely to be read.

The repository should add a tool only when it catches a recurring, meaningful class of error. A tool that forces awkward prose or duplicates editorial review is not helping.

Repository structure

js-learning/
├── README.md
├── docs/
│   ├── CURRICULUM.md
│   ├── ARTICLE_GUIDE.md
│   └── TOOLCHAIN.md
└── articles/
    ├── README.md
    ├── 01-what-javascript-is.md
    ├── 02-running-javascript.md
    └── ...

An article may receive a directory for diagrams or other genuine assets later. Code snippets should remain embedded in the prose.

Markdown and navigation checks

A lightweight automated check may eventually validate:

• Broken relative links.
• Missing linked files and assets.
• Duplicate heading anchors where they make navigation ambiguous.
• Trailing whitespace and malformed fenced code blocks.
• Basic Markdown structure.

Formatting tools should not aggressively reflow prose or tables. The writing is the product; mechanical consistency is secondary to readable paragraphs.

The article index and curriculum should link directly to completed articles. Planned articles should remain unlinked until files exist.

Reviewing embedded code

Every code fence should be reviewed for:

• Correct syntax for its declared language.
• Correct comments and stated output.
• Compatibility with the environment claimed by the surrounding prose.
• Consistency with concepts introduced earlier.
• Clear separation between JavaScript, TypeScript, host APIs, and framework APIs.
• Absence of accidental reliance on an undeclared package or global.

Small fragments often depend on names introduced by the surrounding paragraph and do not need to be executable as standalone files.

For an important multi-step case study, the author should assemble and run the completed form in a temporary scratch environment. That scratch code does not become a parallel source tree in the course.

Snippets intentionally demonstrating an error should say whether the problem is a syntax error, runtime exception, type-checking diagnostic, or merely undesirable behavior.

Technical review

Automated checks cannot establish that an article teaches the correct mental model. Each article should receive a technical review that asks:

1. Is the central explanation accurate?
2. Are any claims environment- or version-dependent without saying so?
3. Do embedded examples behave as described?
4. Are important edge cases omitted or overemphasized?
5. Does the article assume knowledge not yet introduced?
6. Are comparisons with prior languages rare, necessary, and accurate?
7. Does the article distinguish language rules from host behavior and community convention?
8. Does the article repeat material already covered without adding a new perspective?
9. Does the transition into the following article make sense?

An independent reviewer is valuable because one author can repeat the same mistaken assumption consistently through prose and examples.

Version-sensitive material

Some topics change faster than the language fundamentals:

• Supported Node.js and Bun features.
• Native TypeScript execution.
• Package-manager behavior.
• ESLint configuration conventions.
• TypeScript compiler options.
• React framework architecture.
• Browser support for newly standardized APIs.

Articles making version-sensitive claims should link to primary documentation and avoid unnecessary exact version numbers. During maintenance, review these articles first.

Stable language semantics should normally cite the ECMAScript specification indirectly through accessible primary references such as MDN unless specification-level detail is itself the topic.

Integrated case-study review

Longer case studies should be checked as coherent designs even though readers are not asked to implement them.

Review whether:

• Each stage follows from the previous one.
• Code omitted for brevity is clearly identified.
• Later snippets do not silently change earlier contracts.
• Runtime boundaries and side effects remain visible.
• The final form would work if assembled.
• The case study supports the article rather than overwhelming it.

When practical, execute the assembled final form in a temporary directory. Record any important corrections in the article, not in a retained test harness.

Agent authoring protocol

When an agent writes or revises an article:

1. Read the curriculum context and preceding articles.
2. Identify the article's central question and mental model.
3. Draft a connected narrative with embedded examples.
4. Check every example and stated output.
5. Assemble and execute substantial case studies temporarily when useful.
6. Remove template-like sections that do not help the topic.
7. Check that prior-language comparisons are rare and necessary.
8. Verify relative links.
9. Perform a separate technical and continuity review.

An agent must distinguish “written” from “reviewed” and from “executed.” It should report which forms of validation were actually performed.

Course-level review

After completing a part, read the articles in order rather than reviewing each only in isolation. Look for:

• Repeated introductions to the same concept.
• Terminology that changes between articles.
• Examples that use syntax before it is explained.
• Missing transitions.
• Abrupt shifts in assumed knowledge or prose density.
• Overuse of caveats that interrupt the main explanation.
• Topics promised earlier but never developed.

The course should feel like one authored work, not a directory of independently generated reference pages.

Current maintenance order

All six parts are now represented by written articles. Future passes should:

1. Read one complete part in sequence and resolve repetition or continuity issues.
2. Re-run every executable snippet affected by a technical revision.
3. Revisit version-sensitive runtime, browser, TypeScript, React, and tooling claims.
4. Verify navigation and relative links after files are moved or renamed.
5. Record which checks were performed rather than describing a draft as generically “validated.”

No root JavaScript toolchain is required merely to read the course. Add automated Markdown, prose, or link checks only when they address a recurring maintenance problem.