DOCS FEAT: Complete Technical Writer Tutorial

ajay-dhangar · ajay-dhangar · commit 8d71797187de · 2025-11-08T15:26:45.000+05:30
diff --git a/docs/ai-ml/ai-agents/index.mdx b/docs/ai-ml/ai-agents/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/ai-ml/ai-data-scientist/index.mdx b/docs/ai-ml/ai-data-scientist/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/ai-ml/ai-engineer/index.mdx b/docs/ai-ml/ai-engineer/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/ai-ml/ai-red-teaming/index.mdx b/docs/ai-ml/ai-red-teaming/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/ai-ml/bi-analyst/index.mdx b/docs/ai-ml/bi-analyst/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/ai-ml/data-analyst/index.mdx b/docs/ai-ml/data-analyst/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/ai-ml/data-engineer/index.mdx b/docs/ai-ml/data-engineer/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/ai-ml/index.mdx b/docs/ai-ml/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/ai-ml/machine-learning/index.mdx b/docs/ai-ml/machine-learning/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/ai-ml/prompt-engineering/index.mdx b/docs/ai-ml/prompt-engineering/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/angular/index.mdx b/docs/angular/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/aspnet-core/index.mdx b/docs/aspnet-core/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/aws/index.mdx b/docs/aws/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/cloudflare/index.mdx b/docs/cloudflare/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/code-review/index.mdx b/docs/code-review/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/computer-science/index.mdx b/docs/computer-science/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/design/design-system/index.mdx b/docs/design/design-system/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/design/index.mdx b/docs/design/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/design/ux-design/index.mdx b/docs/design/ux-design/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/developer-relations/index.mdx b/docs/developer-relations/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/devops/index.mdx b/docs/devops/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/docker/index.mdx b/docs/docker/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/java/index.mdx b/docs/java/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/kubernetes/index.mdx b/docs/kubernetes/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/laravel/index.mdx b/docs/laravel/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/linux/index.mdx b/docs/linux/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/management/engineering-manager/index.mdx b/docs/management/engineering-manager/index.mdx
diff --git a/docs/management/index.mdx b/docs/management/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/management/product-manager/index.mdx b/docs/management/product-manager/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/mongodb/index.mdx b/docs/mongodb/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/nextjs/index.mdx b/docs/nextjs/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/rust/index.mdx b/docs/rust/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/shell-bash/index.mdx b/docs/shell-bash/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/software-architect/index.mdx b/docs/software-architect/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/software-design-architecture/index.mdx b/docs/software-design-architecture/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/spring-boot/index.mdx b/docs/spring-boot/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/sql/index.mdx b/docs/sql/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/swift-ui/index.mdx b/docs/swift-ui/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/system-design/index.mdx b/docs/system-design/index.mdx
@@ -0,0 +1 @@
+<ComingSoon />
diff --git a/docs/technical-writer/advanced/localization-and-accessibility.mdx b/docs/technical-writer/advanced/localization-and-accessibility.mdx
@@ -1 +1,62 @@
-<ComingSoon />
+---
+title: Localization and Accessibility
+sidebar_label: "2. Localization and Accessibility"
+description: "Advanced principles for designing documentation that can be easily translated (localized) and used by people with disabilities (accessible)."
+---
+
+Professional documentation doesn't stop at the English language, nor does it assume all users have perfect vision or motor skills. **Localization (L10N)** and **Accessibility (A11Y)** are advanced practices that ensure your content is ready for a global and diverse audience.
+
+## 1. Localization (L10N): Writing for Translation
+
+Localization is the process of adapting a product or content to a specific target market, including language translation and cultural adjustments. As a technical writer, your primary job is to make your source English content easy and cost-effective to translate.
+
+### **A. Global-Ready Writing**
+
+Before translation starts, optimize your source text:
+
+* **Avoid Idioms and Slang:** Phrases like "hit the ground running," "low-hanging fruit," or "piece of cake" do not translate literally and cause confusion or require costly rewriting.
+    * **Bad:** "You'll need to hit the ground running with this new feature."
+    * **Good:** "You will need to quickly begin using this new feature."
+* **Keep Sentences Short and Direct:** Complex, compound sentences are easily mangled by translation software and human translators alike. Use one idea per sentence.
+* **Be Consistent (Especially in Style Guides):** Translators often rely on glossaries. If you call an element the "Dashboard" in one place and the "Admin Panel" in another, you force the translator to guess, leading to errors. Stick to your defined terminology.
+* **Minimize Text in Images:** When text is embedded in a screenshot or diagram (e.g., callout labels), it cannot be easily extracted for translation without recreating the image for every language. Use captions or external lists instead.
+
+### **B. Tooling and Process**
+
+Most modern Docs-as-Code platforms support localization through external files.
+
+1.  **Extract Strings:** Your content management system (or localization tool) extracts the translatable text (strings) from your Markdown files (e.g., `.mdx`) and places them into key-value files (e.g., `.json`, `.po`, or `.xliff`).
+2.  **Translation:** These string files are sent to human translators or machine translation services.
+3.  **Insertion:** The translated strings are loaded back into the documentation build process, creating separate language sites (e.g., `/docs/en`, `/docs/de`, `/docs/ja`).
+
+:::warning Context is King
+When working with translators, provide **context**. If a string is "Open," specify whether it's the verb (e.g., "Open the file") or the adjective (e.g., "The API is Open"). This avoids grammatical errors in languages with gendered nouns.
+:::
+
+## 2. Accessibility (A11Y): Designing for Inclusive Use
+
+Accessibility means ensuring people with disabilities—including visual, auditory, cognitive, and motor impairments—can perceive, understand, navigate, and interact with your documentation. This is often mandated by law (like the WCAG standards) and is always a matter of good practice.
+
+### **A. Visual Accessibility**
+
+This primarily helps users who rely on screen readers or have low vision.
+
+* **Semantic HTML and Headings:** Always use proper Markdown headings (`#`, `##`, `###`). Screen readers use these to create a navigable outline. **Never skip heading levels** (e.g., going directly from an `##` to an `####`). 
+* **Alt Text for Images:** Every instructional image, diagram, or chart must have descriptive "alternative text." Screen readers read this text aloud, providing context for non-sighted users.
+    * **Bad:** `![Diagram]`
+    * **Good:** `![Diagram showing the Authentication Flow: User sends credentials to the server, server returns an OAuth token, which the user then includes in all API requests.]`
+* **Color Contrast:** Ensure a high color contrast ratio between text and the background (e.g., dark text on a light background). Avoid using color alone to convey meaning (e.g., "The red text indicates an error").
+
+### **B. Navigation and Input Accessibility**
+
+This addresses users who cannot use a mouse.
+
+* **Keyboard Navigation:** All interactive elements (search bars, navigation menus, code tabs) must be accessible using only the keyboard's **Tab** key. The focus indicator (a visible outline around the element) must be clear.
+* **Descriptive Links:** Links should clearly indicate their destination, even when read out of context.
+    * **Bad:** "To learn more, **click here**."
+    * **Good:** "To learn more, read the **Security Overview guide**."
+* **Transcripts for Videos:** If you embed video tutorials, always provide a full, accurate text transcript or closed captions for users who are deaf or hard of hearing.
+
+---
+
+By prioritizing global-ready content and adhering to WCAG standards, you move beyond simply writing words and embrace the role of a true **Information Designer**, creating documentation that is open and useful to everyone, everywhere.
diff --git a/docs/technical-writer/advanced/open-source-contributions.mdx b/docs/technical-writer/advanced/open-source-contributions.mdx
@@ -1 +1,83 @@
-<ComingSoon />
+---
+title: Open Source Contributions
+sidebar_label: "4. Open Source Contributions"
+description: "Learn the technical and social etiquette of contributing documentation to open-source projects, a vital step for advancing your technical writing career."
+---
+
+Contributing to open-source (OSS) documentation is a pivotal step in a technical writer's career. It gives you hands-on experience with modern tools (like Git, Markdown, and various SSGs) and demonstrates your ability to collaborate with engineering teams on critical, live codebases.
+
+## 1. Why Contribute to OSS Docs?
+
+It's a high-impact, low-risk way to learn and prove your skills.
+
+| Benefit | Description |
+| :--- | :--- |
+| **Portfolio Builder** | A merged Pull Request (PR) on a major project (like Kubernetes, React, or a popular Node library) is the best proof of your skills you can offer a potential employer. |
+| **Tooling Mastery** | You gain practical experience using **Git/GitHub**, working with **Markdown/MDX**, and navigating complex **Static Site Generators (SSGs)**. |
+| **Learn Best Practices** | You are forced to adhere to a project's strict **style guides** and **submission workflows**, which are often best-in-class. |
+| **Networking** | You interact directly with core maintainers and engineers, expanding your professional network. |
+
+## 2. Finding a Project and Your First Contribution
+
+Don't start by trying to rewrite the whole manual. Start small, targeted, and highly valuable.
+
+### A. Finding the Right Project
+
+* **Use the Tools You Know:** Start with a project whose technology you already use (e.g., if you use Python, look at Django or Flask docs). You already understand the user pain points.
+* **Look for Doc Gaps:** Look for sections in documentation that are sparse, confusing, or outdated.
+* **Good Starter Projects:** Many projects use labels like `good first issue`, `documentation`, or `help wanted` on their GitHub issue trackers. 
+
+### B. The Easiest Wins (Low-Friction Contributions)
+
+1.  **Fix Typos and Grammar:** Spotting a misplaced comma or a typo is an easy way to get familiar with the project's **Git workflow** and earn your first merged PR.
+2.  **Clarify Error Messages:** If a step throws a confusing error, clarify what the error means and provide a direct solution or workaround.
+3.  **Update Outdated Commands:** Sometimes the documentation uses an old command line flag or package name. Verifying and updating these is highly valuable.
+4.  **Enhance the README:** The `README.md` is the project's front door. Improving its clarity, adding prerequisites, or cleaning up the installation instructions is a great contribution.
+
+## 3. The Contribution Workflow (Technical Etiquette)
+
+Contributing documentation requires strict adherence to the project’s technical workflow, which is almost always based on Git and GitHub.
+
+### Step 1: **Fork and Clone**
+
+* **Fork:** Click the **Fork** button on the project's GitHub page. This creates a personal copy of the entire repository under your account.
+* **Clone:** Clone your personal fork to your local machine.
+
+```bash title="Terminal"
+git clone https://github.com/your-username/project-name.git
+```
+
+### Step 2: **Create a New Branch**
+
+```bash title="Terminal"
+cd project-name
+```
+
+Always isolate your change in a new branch. Use the naming convention (if provided by the project, e.g., `docs/fix-readme`).
+
+```bash title="Terminal"
+git checkout -b docs/fix-broken-link
+```
+
+### Step 3: **Commit with Clarity**
+
+  * Make your changes locally.
+  * Commit your changes using a clear, descriptive commit message that follows the project's style. Use a prefix like `DOCS:` or `FIX:`
+      * **Good Commit:** `DOCS: Clarified prerequisites in installation tutorial`
+
+### Step 4: **Open the Pull Request (PR)**
+
+  * **Push:** Push your new branch to your fork on GitHub.
+  * **PR:** Navigate to the original project repository on GitHub and click the **Compare & Pull Request** button.
+  * **Fill out the Template:** Most serious projects have a **PR template**. **Fill it out completely!** Explain *what* you changed and *why* (e.g., "The previous steps failed on Windows," or "I added a section on error handling").
+
+## 4. The Social Etiquette (Non-Technical Rules)
+
+Technical writers are collaborators. A positive, respectful interaction is essential.
+
+1.  **Read the Contribution Guide:** Before you do anything, find the project's `CONTRIBUTING.md` file. It explains the PR process, required testing, and preferred style guides.
+2.  **Be Humble and Patient:** A core maintainer is volunteering their time. They might take days or weeks to review your work. Be polite, respond clearly to their feedback, and avoid demanding quick merges.
+3.  **Accept Feedback (and Refactor):** Expect suggestions. Maintainers may ask you to rewrite sentences, move a section, or change your branch name. This is normal; it’s part of adhering to the project's standards.
+4.  **Close the Loop:** If you opened an issue for a problem you fixed, reference the issue in your PR description (e.g., "Closes \#1234").
+
+Open-source contribution is the gold standard for proving your technical writing skills, offering continuous learning, and directly impacting the developer community.
diff --git a/docs/technical-writer/advanced/seo-for-documentation.mdx b/docs/technical-writer/advanced/seo-for-documentation.mdx
@@ -1 +1,74 @@
-<ComingSoon />
+---
+title: SEO for Documentation
+sidebar_label: "3. SEO for Documentation"
+description: "Advanced techniques for optimizing documentation content, metadata, and site structure to rank higher in search engines and serve user needs directly."
+---
+
+**Search Engine Optimization (SEO)** is the process of improving your documentation's visibility so users can find the answers they need quickly, often bypassing your primary navigation entirely. For technical content, this means ranking well for **problem-solving queries** like "how to install X" or "Y API error code."
+
+The core principle of docs SEO is simple: **Solve the user's problem better than anyone else.**
+
+## 1. On-Page Optimization: Content is King
+
+The first place to optimize is within the content itself. You must align your writing with the terms your audience is actually searching for.
+
+### A. Keyword Research (The User's Question)
+
+Your users rarely search for product names alone; they search for **solutions**.
+
+* **Focus on Long-Tail Keywords:** These are specific phrases that indicate a strong intent to solve a problem.
+    * **Bad:** *API*
+    * **Good:** *"API error 401 unauthorized fix"* or *"docusaurus deploy github pages failure"*
+* **Use the Exact Language of the Problem:** If the command is `npm install`, your content should use that exact phrase, not synonyms like "npm setup" or "package fetching."
+
+### B. Strategic Keyword Placement
+
+Use your target keywords naturally in the most important sections of the page:
+
+1.  **Title:** The page title (defined in the front matter) is the single most important ranking signal.
+2.  **Description:** The page description (also in the front matter) doesn't directly affect ranking, but it becomes the snippet of text shown in Google's results—it must be compelling and accurate.
+3.  **Headings (H2/H3):** Include keywords naturally in your section headings to establish content hierarchy.
+4.  **Body Text:** Use the keywords in the first paragraph, and maintain a natural density throughout the article.
+
+### C. Optimize Code Blocks and Tables
+
+Search engines primarily read plain text. Ensure your solutions are available in an easily crawlable format:
+
+* **Code Blocks:** Ensure your code blocks have clear, descriptive text explaining their purpose *before* the code itself.
+* **Error Codes:** Dedicate a section or table to error codes. A table with columns for **Error Code, Meaning, and Solution** is highly crawlable and often appears as a **Featured Snippet** in Google.
+
+## 2. Technical SEO: Docusaurus and Structure
+
+Technical SEO ensures that search engine bots can effectively crawl, index, and understand your documentation site. Docusaurus handles much of this automatically, but you must configure it correctly.
+
+### A. Front Matter (The Metadata)
+
+The MDX front matter (the block at the top of your file) is crucial for SEO and sharing.
+
+* `title:`: Should be concise and contain the primary keyword.
+* `description:`: A compelling, 150–160 character summary of the content.
+* `slug:`: The end of the URL. Ensure your slugs are descriptive and contain keywords (e.g., `/api-error-401-fix` is better than `/page-15`).
+
+### B. Internal Linking (The Connective Tissue)
+
+Internal links signal to search engines which pages on your site are most important and help bots discover new content.
+
+* **Connect Concepts:** When you mention a related topic (e.g., "See the **API Reference** for details..."), ensure the term is a direct link to the relevant page.
+* **Navigation:** Your Docusaurus sidebar acts as a major source of internal links, ensuring all main pages are reachable and discoverable.
+
+### C. Sitemaps and Robots.txt
+
+* **Sitemaps:** Docusaurus automatically generates a `sitemap.xml` file, which lists all the crawlable pages on your site. **Submit this to Google Search Console.**
+* **Robots.txt:** This file tells search bots which parts of your site *not* to crawl. Use it sparingly, mainly to block utility pages or old, duplicated content that you don't want indexed.
+
+## 3. SEO-Driven Content Strategy
+
+Use SEO insights to drive your content creation, ensuring you always write what people need.
+
+* **Focus on the Missing Manuals:** Use Google Search Console or analytics to identify common queries that lead to a "404 Not Found" or a high bounce rate. These represent content gaps you need to fill.
+* **The "How-To" Structure:** The user is often looking for a task. Structure your content as a clear, numbered list of steps, as this format is often preferred by Google for **Featured Snippets** (the summary box at the top of search results). 
+* **Measure and Iterate:** Use tools like **Google Search Console** and **Google Analytics** to track which queries bring users to your site and whether those users are finding what they need (low bounce rate). Optimize pages with high traffic but poor engagement.
+
+---
+
+By applying these SEO principles, you ensure your documentation is not only accurate but also easily accessible to the global community of developers who rely on search to find immediate answers.
diff --git a/docs/technical-writer/advanced/technical-writing-career-path.mdx b/docs/technical-writer/advanced/technical-writing-career-path.mdx
diff --git a/docs/technical-writer/advanced/writing-for-developers.mdx b/docs/technical-writer/advanced/writing-for-developers.mdx
diff --git a/docs/technical-writer/resources/books-and-courses.mdx b/docs/technical-writer/resources/books-and-courses.mdx
diff --git a/docs/technical-writer/resources/communities-and-blogs.mdx b/docs/technical-writer/resources/communities-and-blogs.mdx
diff --git a/docs/technical-writer/resources/portfolio-building.mdx b/docs/technical-writer/resources/portfolio-building.mdx
diff --git a/docs/technical-writer/resources/templates-and-samples.mdx b/docs/technical-writer/resources/templates-and-samples.mdx
diff --git a/docs/technical-writer/tools/docs-platforms.mdx b/docs/technical-writer/tools/docs-platforms.mdx
diff --git a/docs/technical-writer/tools/markdown-basics.mdx b/docs/technical-writer/tools/markdown-basics.mdx
diff --git a/docs/technical-writer/tools/style-guides.mdx b/docs/technical-writer/tools/style-guides.mdx
diff --git a/docs/technical-writer/tools/version-control-github.mdx b/docs/technical-writer/tools/version-control-github.mdx
diff --git a/docs/technical-writer/tools/writing-tools.mdx b/docs/technical-writer/tools/writing-tools.mdx
diff --git a/docs/terraform/index.mdx b/docs/terraform/index.mdx
diff --git a/docs/typescript/index.mdx b/docs/typescript/index.mdx
diff --git a/docs/vue/index.mdx b/docs/vue/index.mdx
diff --git a/src/components/LinkCard.tsx b/src/components/LinkCard.tsx
