Site-Wide Student Enrichment Design

Goal

Upgrade all study content in docs/ so pages are more useful to students for learning, revision, exams, interviews, and practical application. The enrichment should add teaching structure, diagrams, examples, and practice material without adding filler.

Scope

The project currently contains about 2,024 Markdown/MDX files under docs/.

The enrichment applies to:

• All non-index study pages under docs/.
• All subject and chapter index.md pages, using a lighter learning-path format.
• Existing recently completed pages from the incomplete-content pass.

The enrichment does not apply to:

• Blog posts.
• Static assets unless a page needs a new local image.
• Navigation restructuring unless a broken page requires a local link correction.

Student-First Page Pattern

Each non-index study page should move toward this structure, adapted to the topic:

1. Learning Objectives

   • 3 to 6 concrete outcomes.
   • Use student-facing verbs such as explain, compare, calculate, trace, identify, apply, design, evaluate.

2. Concept Map or Flowchart

   • Use Mermaid diagrams for workflows, classifications, algorithms, processes, legal reasoning, clinical reasoning, or system architecture.
   • Use tables or text diagrams when Mermaid would not add clarity.

3. Core Explanation

   • Clear definitions first.
   • Explain why the topic matters.
   • Break complex ideas into short, titled sections.

4. Worked Example, Case, or Dry Run

   • Software pages: dry run, state changes, complexity reasoning.
   • Law pages: issue-rule-application-conclusion style case analysis.
   • Medicine/pharmacy pages: clinical reasoning, safety notes, and non-prescriptive educational framing.
   • Electronics/engineering pages: circuit, formula, or process example.
   • Business/economics pages: numeric example or decision scenario.
   • Hotel management pages: service, kitchen, operations, or guest-handling scenario.

5. Common Mistakes

   • Misconceptions, exam traps, implementation pitfalls, or unsafe assumptions.

6. Quick Revision Table

   • Compact comparison, formula summary, key terms, or process checklist.

7. Practice Questions

   • 3 to 6 questions, mixing recall, application, and analysis.

8. Key Takeaways

   • 3 to 5 concise points.

Index Page Pattern

Subject and chapter index.md pages should use a lighter structure:

• What this section covers.
• Suggested learning path.
• How topics connect.
• Revision strategy.
• Links should remain compatible with existing Docusaurus routes.

Index pages should not be padded with full lesson content that belongs on child pages.

Visual Policy

Visuals must teach. Avoid decorative images.

Preferred visual types:

• Mermaid flowcharts for processes and decision trees.
• Mermaid sequence diagrams for protocols, request/response flows, or workflows.
• Mermaid mind maps only where supported by the site build and useful.
• Tables for comparisons and revision.
• Text diagrams for simple circuits, memory layouts, stacks, queues, trees, and state machines.
• Local generated images only where a raster visual substantially improves learning, such as anatomy, lab instruments, circuit layout, kitchen workflow, or hospitality setup.

Rules:

• Do not use remote placeholder images.
• Do not add large image files without a clear teaching purpose.
• Keep diagrams small enough to read on mobile.
• Mermaid syntax must be build-safe for Docusaurus/MDX.
• Avoid raw LaTeX braces that MDX may interpret as JavaScript. Use code blocks or escaped syntax when needed.

Subject-Specific Guidance

Software Interview Prep

Add:

• Problem pattern.
• Flowchart or decision diagram where helpful.
• Dry run with a small input.
• Complexity explanation tied to the code.
• Edge cases and interview tips.

Computer Science

Add:

• Concept maps.
• Algorithm traces.
• System diagrams.
• Tables comparing models, protocols, data structures, or design choices.

Electronics

Add:

• Circuit/process diagrams.
• Formula meaning in plain language.
• Worked calculations.
• Measurement and troubleshooting notes.

Medicine, Pharmacy, and Biotechnology

Add:

• Educational clinical/lab reasoning.
• Safety and ethics notes where relevant.
• Mechanism diagrams.
• Comparison tables.

Fact-check against reliable sources before adding current or high-stakes claims. Avoid giving personal medical advice.

Law

Add:

• Statutory framework.
• Issue-rule-application-conclusion analysis.
• Procedure flowcharts.
• Current-law notes where statutes have changed.

Fact-check current legal references against official or reliable legal sources.

Economics, Business, and Commercial Applications

Add:

• Graph/process explanations.
• Worked numeric examples.
• Decision frameworks.
• Revision tables.

Hotel Management

Add:

• Operational workflows.
• Guest-service scenarios.
• Production and service checklists.
• Safety, hygiene, and quality-control notes.

Psychology

Add:

• Theory maps.
• Experiment or assessment interpretation.
• Application examples.
• Ethics notes.

Rollout Strategy

Use phased batches to protect quality and build stability.

Recommended order:

1. docs/Software_engineer_interview_prep/
2. docs/Computer_Science/
3. docs/Electronics/
4. docs/Bio_Technology/
5. docs/Medicine/
6. docs/Pharmacy/
7. docs/Law/
8. docs/Economics/
9. docs/Business_Administration/
10. docs/Commercial_Applications/
11. docs/Hotel_Management/
12. docs/Psychology/
13. Remaining docs such as docs/Index/

Each phase should be independently verifiable and committed.

Quality Checks

For each phase:

• Run a targeted scan for placeholders and generator residue.
• Run a Markdown code-fence balance scan.
• Run npm run build after the batch or after a manageable group of batches.
• Review a sample of pages manually for diagram readability and content relevance.

For high-stakes factual subjects:

• Check current claims against reliable/current sources.
• Prefer official sources for law and regulation.
• Prefer authoritative medical/pharmacy references for clinical claims.

Success Criteria

The enrichment is successful when:

• Pages are easier for students to study and revise.
• Visuals clarify the material rather than decorate it.
• Pages contain concrete examples, practice questions, and common mistakes.
• Docusaurus builds successfully.
• No new placeholder, broken Mermaid, broken MDX, or unbalanced code-fence issues are introduced.

Risks and Mitigations

Risk	Mitigation
2,024-page scope becomes too large to review	Work in subject batches and commit each phase.
Diagrams break MDX build	Use conservative Mermaid syntax and build after batches.
Content becomes generic	Use subject-specific templates and examples.
Current legal/medical facts become inaccurate	Verify high-stakes claims with reliable sources during those phases.
Pages become too long	Prioritize learning value; keep sections concise and useful.

Out of Scope

• Full site redesign.
• Blog enrichment.
• Dependency upgrades.
• Fixing pre-existing broken anchors, undefined tags, or unrelated blog warnings unless directly touched by this work.