From 1c07430f4b7cae77c19ccb85075268675ddd684e Mon Sep 17 00:00:00 2001 From: Ajay Dhangar Date: Tue, 4 Nov 2025 09:36:19 +0530 Subject: [PATCH] added ne doc --- docs/index.mdx | 46 +++--- .../document-structure-and-formatting.mdx | 152 +++++++++++++++++- src/theme/MDXComponents.js | 4 +- 3 files changed, 175 insertions(+), 27 deletions(-) diff --git a/docs/index.mdx b/docs/index.mdx index 198eb6e..447a0e6 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -6,10 +6,10 @@ slug: / --- - CodeHarborHub Tutorials | Learn HTML, CSS, JavaScript, and More + CodeHarborHub Tutorials - +**CodeHarborHub** is your free, open-source resource for mastering modern technology. Whether you’re a **beginner aiming to land your first tech job** or a **professional looking to master the latest frameworks**, we provide the comprehensive, project-based tutorials you need to succeed. -Our mission is to provide accessible and comprehensive educational resources for all levels — from beginners to professionals. Whether you want to **kickstart your career**, **master a new language**, or **stay updated with the latest tech**, you’ll find everything you need here. +Stop consuming content—start **creating** it. Our platform is built by experienced developers and open-source contributors dedicated to practical, hands-on learning. -With a team of experienced instructors and open-source contributors, we offer a wide range of tutorials designed to help you grow your skills with hands-on learning. - ## What is CodeHarborHub?
-**CodeHarborHub** is a free platform that empowers learners with structured tutorials, project-based lessons, and real-world challenges. -We cover topics including **Frontend**, **Backend**, **AI**, **Data Science**, and **Cloud Computing**. +We're more than just a tutorial site—we're a dedicated learning ecosystem. **CodeHarborHub** provides structured, challenge-based lessons across the most in-demand technical fields: **Frontend**, **Backend**, **AI/ML**, **Data Science**, and **Cloud Computing**. Our goal is to transform theoretical knowledge into *deployable, real-world skills*. + +## Why Choose CodeHarborHub? -## Why Learn with CodeHarborHub? +We focus on delivering **real-world value** that directly impacts your career and skills. -- **Completely Free** — Access all tutorials anytime, anywhere. -- **Project-Based Learning** — Build hands-on projects and grow your portfolio. -- **Beginner to Advanced** — Learn at your own pace with structured paths. -- **Community Support** — Collaborate, share, and contribute to open-source projects. -- **Continuous Updates** — Stay up-to-date with modern frameworks and technologies. +* **100% Free & Accessible:** No paywalls, no hidden fees. Get complete access to all structured tutorials, anytime, anywhere. +* **Portfolio-Driven Learning:** Learn by building. Our project-based approach ensures you graduate each lesson with a **deployable project** for your professional portfolio. +* **Structured & Scalable:** Follow clear learning paths designed for every level, from **foundational concepts** to **advanced topics** and modern frameworks. +* **Community & Open Source:** Join an active community of developers. Get support, share knowledge, and contribute to real-world open-source projects. +* **Future-Proof Skills:** Our curriculum is continuously updated by experts to cover the latest frameworks, technologies, and industry best practices. -

Explore Tutorials by Technology

+## Start Your Learning Path + +Select a technology below to dive into our structured tutorials. Each path is designed to take you from the fundamentals to building complete, robust applications.
@@ -116,6 +110,8 @@ We cover topics including **Frontend**, **Backend**, **AI**, **Data Science**, a
-## Get Started Today! +## Ready to Code? + +Your next skill is waiting. Browse the technology paths above to begin your journey with **CodeHarborHub**. -Browse the tutorials above to begin your journey with **CodeHarborHub**. Keep learning, keep building, and let’s create the future of technology together. \ No newline at end of file +**Keep Learning. Keep Building. Let's create the future of technology together.** \ No newline at end of file diff --git a/docs/technical-writer/fundamentals/document-structure-and-formatting.mdx b/docs/technical-writer/fundamentals/document-structure-and-formatting.mdx index e345ed2..b51d156 100644 --- a/docs/technical-writer/fundamentals/document-structure-and-formatting.mdx +++ b/docs/technical-writer/fundamentals/document-structure-and-formatting.mdx @@ -1 +1,151 @@ - \ No newline at end of file +--- +title: Document Structure and Formatting +sidebar_label: "3. Document Structure and Formatting" +description: "Learn how to structure documentation using the modern Diátaxis framework, ensuring users can find and use content efficiently based on their goals." +image: /tutorial/img/tutorials/technical-writer/structure-and-formatting-cover.png +--- + +import { FaBook, FaWrench, FaCode, FaLightbulb } from 'react-icons/fa'; + +Writing well is only half the battle. If your users can't find the information they need, or if the content they find mixes learning materials with quick facts, your documentation fails. + +**Information Architecture (IA)** is the practice of organizing and labeling content so users can find what they need. The most effective modern approach to technical documentation IA is the **Diátaxis Framework**. + +:::tip Information Architecture Overview + +
+ +```mermaid + graph TD + A[Information Architecture ] --> B[Organizing & Labeling Content] + A --> C[Goal: Help Users Find What They Need] + A --> D[Modern Approach → Diátaxis Framework] + + %% Diátaxis Core Branches + D --> D1[1️⃣ Tutorials
Learning-Oriented Guides] + D --> D2[2️⃣ How-To Guides
Task-Oriented Instructions] + D --> D3[3️⃣ Reference
Information-Oriented Docs] + D --> D4[4️⃣ Explanation
Understanding-Oriented Articles] + + %% Sub-details for Tutorials + D1 --> D1a[Step-by-step walkthroughs] + D1 --> D1b[Clear learning outcomes] + + %% Sub-details for How-To Guides + D2 --> D2a[Goal-driven workflows] + D2 --> D2b[Practical, specific results] + + %% Sub-details for Reference + D3 --> D3a[API Docs, CLI Commands] + D3 --> D3b[Precise, factual content] + + %% Sub-details for Explanation + D4 --> D4a[Concepts, Principles] + D4 --> D4b[“Why” behind functionality] + + %% IA Systems connection + A --> E[IA Systems] + E --> E1[Organization System] + E --> E2[Navigation System] + E --> E3[Labeling System] + E --> E4[Search System] + + %% Relationships + E1 --> D + E2 --> D + E3 --> D + E4 --> D +``` + +In this diagram, you can see how the Diátaxis framework fits into the broader context of Information Architecture (IA) systems, which include organization, navigation, labeling, and search systems. Each of these systems plays a crucial role in ensuring that users can efficiently find and utilize the documentation they need. + +::: + +--- + +## The Diátaxis Framework: Structuring by Need + +The Diátaxis framework is a systematic approach that categorizes all documentation into four distinct types, based on the user's current goal: **are they learning or working?** and **do they need action or cognition (knowledge)?** + +This prevents the single biggest problem in documentation: mixing content types (e.g., putting a conceptual explanation inside an installation guide). + +### The Four Quadrants of Diátaxis + +| Type | User Goal | Content Focus | When to Use | +| :--- | :--- | :--- | :--- | +| **1. Tutorials** | **Learning.** The user is a beginner and wants to learn through practice. | Guided, step-by-step action; minimum theory. | Onboarding a new user; introducing a core workflow. | +| **2. How-To Guides** | **Working.** The user knows the product and wants to achieve a specific task (a "recipe"). | Solutions to real-world problems; task-focused steps. | Guides for a specific setup (e.g., "How to integrate with Slack"). | +| **3. Reference** | **Working.** The user needs a precise fact about the system for quick look-up. | Factual, structured information (API parameters, configuration options). | API Documentation, configuration tables, command line syntax. | +| **4. Explanation** | **Learning.** The user wants to understand the *why* and the *how* of the system deeply. | Theoretical and contextual discussion; big picture; rationale. | Design principles, architecture overviews, technical background. | + +
+ } + /> + } + /> + } + /> + } + /> +
+ +### Why This Matters + +By adopting a framework like Diátaxis, you ensure that: + +1. **Users find the right content:** A new user looking to learn goes straight to 'Tutorials' instead of struggling with 'Reference' material. +2. **Content stays focused:** Your 'How-To Guide' only contains steps (actions), not long conceptual paragraphs (explanations). +3. **Your documentation is complete:** The framework acts as an audit checklist, exposing missing content types (e.g., "We have great tutorials, but no theoretical 'Explanation' for the architecture"). + +--- + +## Best Practices for Page-Level Formatting + +While Diátaxis manages the macro-structure (folders and navigation), consistent formatting manages the micro-structure (the page itself). + +### 1. Headings (H1, H2, H3) + +Use headings to create a clear, nested hierarchy that helps users scan the page. The goal is that a user should be able to read only the headings and still understand the flow of the document. + +* **H1 (`#`):** Used only once per page (the title). +* **H2 (`##`):** Main sections of the document. +* **H3 (`###`):** Sub-steps or topics within an H2 section. + +### 2. Lists and Steps + +Procedural information must be instantly digestible. + +| Type | Purpose | Example | +| :--- | :--- | :--- | +| **Numbered Lists** | For sequential steps (e.g., installation). **Always use these for tasks.** | `1. Run the command.` `2. Check the output.` | +| **Bullet Lists** | For non-sequential items (e.g., features, requirements, key concepts). | `- Feature A` `- Feature B` | +| **Definition Lists** | Use tables or bold formatting for key/value pairs (e.g., API parameters). | **`--config`** | The path to your configuration file. | + +### 3. Code Blocks and Inline Code + +Code is the most critical element. Always use the appropriate formatting: + +* **Inline Code:** Use single backticks (`` ` ``) for file names, variable names, command flags, and error messages. + * *Example:* The variable `` `API_KEY` `` must be set in `` `config.env` ``. +* **Code Blocks:** Use triple backticks (`` ``` ``) with language highlighting for larger code examples, scripts, or command line output. + * *Example:* + ```bash + # Always specify the language (e.g., bash, json, javascript) + npm install codeharborhub-cli + ``` + +:::tip Use Admonitions for Clarity +Use Docusaurus's built-in admonition blocks (like this tip box, or `:::note`, `:::warning`) to draw the user's attention to critical, supplementary, or conditional information without disrupting the main flow of the steps. +::: \ No newline at end of file diff --git a/src/theme/MDXComponents.js b/src/theme/MDXComponents.js index 8086158..6b6a4b6 100644 --- a/src/theme/MDXComponents.js +++ b/src/theme/MDXComponents.js @@ -16,6 +16,7 @@ import ComingSoon from '@site/src/components/ComingSoon'; import AuthorProfile from '@site/src/components/AuthorProfile'; import Link from '@docusaurus/Link'; import ToolCard from '@site/src/components/ToolCard'; +import SkillCard from '@site/src/components/SkillCard'; export default { // Re-use the default mapping @@ -34,5 +35,6 @@ export default { ComingSoon, Link, AuthorProfile, - ToolCard + ToolCard, + SkillCard, };