+ +Having the right tools is just the beginning. **Best practices** are the rules that ensure your documentation is clear, accurate, and scalable over time. + +These guidelines are focused on maintaining high quality in a modern, developer-centric environment. + +## 1. Adopt the Diátaxis Framework + +This is the single most important rule for structuring your documentation. The Diátaxis framework helps you categorize content based on the user's intent, solving the problem of "where do I put this?" + +| Type | User Intent | Primary Goal | Best Practice | +| :--- | :--- | :--- | :--- | +| **Tutorials** | Learning how to do something new. | Teach the user, step-by-step. | **Hands-on, single path.** Start with "Hello World" and end with success. | +| **How-To Guides** | Solving a specific problem. | Show how to achieve a goal. | **Focused, actionable steps.** Title should be a verb: "Configure," "Integrate," "Troubleshoot." | +| **Conceptual** | Understanding the topic/product. | Explain the why and the how it works. | **High-level, narrative.** Use diagrams (Mermaid!) and analogies. | +| **Reference** | Looking up technical specifics. | Provide accurate technical details. | **Structured, pure facts.** Use tables, parameters, and code snippets. | + +
+ +:::tip Best Practice +Never mix document types. Do not put conceptual explanations inside a How-To Guide, or a reference table inside a Tutorial. Link, don't combine. +::: + +## 2. Embrace the Docs-as-Code Workflow + +Since you're using Docusaurus, you are already committed to this workflow. Maximize its benefits: + +### 2.1 Treat Docs Like Code + +* **Version Control:** Use Git. Commit early and often. Every content change should be traceable to a specific, descriptive commit message. +* **Pull Requests (PRs):** All content changes should go through a PR process. This enables peer review from developers (for technical accuracy) and other writers (for clarity and style). +* **Branching:** Always work on a separate feature branch. The docs for a new feature should live on the same branch as the code for that feature, ensuring they merge and deploy together. + +### 2.2 Prioritize Plain Text + +* **Stick to Markdown/MDX:** Avoid embedding complex formatting or elements that break the portability of the plain text file. The simpler the text file, the easier it is to maintain for years. +* **Automate Quality:** Configure your repository to use a linter (like **write-good** or **Vale**) to check for grammatical, stylistic, and tone errors automatically with every commit. + +## 3. Focus on Clarity and Consistency + +The cardinal sins of documentation are ambiguity and inconsistency. Here’s how to avoid them: + +### 3.1 Write for Your Audience + +* **Define Jargon:** Always define specialized terms on first use. If your audience is diverse, you may need a separate **Glossary** (a Conceptual document!). +* **The Golden Rule:** Always write one level *below* your audience’s presumed knowledge. If you're writing for mid-level developers, explain everything as if you're writing for junior developers. Over-explaining is better than under-explaining. + +### 3.2 Maintain a Style Guide + +Consistency is achieved through rules. If your company doesn't have a technical writing style guide (e.g., *Google Developer Documentation Style Guide*), adopt one. + +| Element | Rule | Example | +| :--- | :--- | :--- | +| **Voice** | Use the active voice and direct address ("you"). | **Good:** You must run the installer. **Bad:** The installer should be run. | +| **UI Elements** | Use **bold** for buttons, screen names, or menu items. | Click the **Settings** menu, then select **Deploy**. | +| **Code** | Use inline code blocks (`code`) for file paths, variable names, and function names. | Set the `MAX_RETRIES` variable in the `config.yaml` file. | + +## 4. Maintenance is Mandatory + +Documentation is not a one-time task; it's a perpetual commitment. If the code changes, the docs *must* change. + +* **Schedule Audits:** Regularly audit your existing documentation. Tools can find broken links, but only a human writer can identify outdated procedures. + * *Self-Correction:* If an old doc is still receiving high traffic but is outdated, either update it or archive it with a clear note linking to the current version. +* **Use Feedback Loops:** Encourage users to report errors or suggest improvements. Docusaurus makes this easy with "Edit this page" links that direct users to GitHub to create a PR. **You are only as good as the feedback you receive.** +* **Deprecation:** When you remove a feature or API, update the documentation *before* the code is merged, or at the very least, simultaneously. Never leave a deprecated feature fully documented. + +You've now established your methodology. The next crucial step is determining *who* you are writing for, which governs everything from tone to vocabulary. \ No newline at end of file diff --git a/docs/technical-writer/intro/skills-required.mdx b/docs/technical-writer/intro/skills-required.mdx new file mode 100644 index 0000000..81d9910 --- /dev/null +++ b/docs/technical-writer/intro/skills-required.mdx @@ -0,0 +1,113 @@ +--- +title: "Skills for Technical Writers" +description: "A breakdown of the technical (hard) and interpersonal (soft) skills every modern technical writer needs to succeed in a Docs-as-Code environment." +sidebar_label: "5. Skills Required" +image: "/tutorial/img/tutorials/technical-writer/skills-required-cover.png" +--- + +import SkillCard from '@site/src/components/SkillCard'; +import thumbnail from '/img/tutorials/technical-writer/skills-required-cover.png'; + +
+ +Think of the technical writer's skill set as a tripod: one leg is **Writing**, one is **Technical Knowledge**, and the third is **Interpersonal (Soft) Skills**. If any one leg is too short, the whole thing tips over. + +Here's the breakdown of the most critical skills you need to cultivate, starting with the measurable, 'hard' skills that get you in the door. + +## 1. Hard Skills: The Measurable Know-How + +These are the job-specific, teachable abilities required to manage content in a Docs-as-Code system. + +### **A. Core Writing & Editing** + +This may seem obvious, but it's the foundation. + +* **Clarity and Conciseness:** The ability to distill complex, often jargony, information into clear, simple, and unambiguous language. Your goal is to reduce cognitive load on the reader. +* **Structure and Flow:** Knowing how to organize information using the **Diátaxis Framework** (Tutorials, How-To Guides, Conceptual, Reference) to ensure the user can find what they need instantly. +* **Proofreading and Consistency:** Meticulous attention to detail regarding grammar, punctuation, and adherence to a specific **style guide** (like the *Google Developer Style Guide*). + +### **B. Technical Tool Proficiency** + +In a Docusaurus environment, you must be comfortable with the infrastructure. + +
+ +
+ +This video, while general, provides a good overview of the differences between hard and soft skills, which is a core concept for aspiring technical writers. \ No newline at end of file diff --git a/docs/technical-writer/intro/tools-for-technical-writers.mdx b/docs/technical-writer/intro/tools-for-technical-writers.mdx new file mode 100644 index 0000000..ec61c7e --- /dev/null +++ b/docs/technical-writer/intro/tools-for-technical-writers.mdx @@ -0,0 +1,192 @@ +--- +title: "The Essential Toolkit for Modern Technical Writers" +sidebar_label: "3. Tools For Technical Writers" +description: "An introduction to the core tools—Markdown, Git, VS Code, and Docusaurus—that power a modern Docs-as-Code workflow for technical writers." +image: /tutorial/img/tutorials/technical-writer/tools-for-technical-writers.png +--- + +import thumbnail from '/img/tutorials/technical-writer/tools-for-technical-writers.png'; + +Welcome to the job! If you're coming from the world of term papers and memos, you might expect your main tool to be Microsoft Word. Think again. + +
+ +In the modern software world, documentation is built like code. This is called the **Docs-as-Code** workflow, and it requires a unique and powerful set of tools that we'll explore here. + +## 1. The Core: Plain Text and Markup + +Every modern documentation site, including this one (built with Docusaurus!), starts with simple text files. + +### A. Markdown and MDX + +Forget proprietary file formats. We use **Markdown** because it’s a lightweight language that’s easy to read, write, and convert into HTML. + +**MDX** is Markdown's superpower. It allows you to embed interactive web components (written in React) directly into your documents. This is how we create custom features like the `ToolCard` you see below! + +
+ +We will focus on the structure promoted by the **Diátaxis framework**, which is the gold standard for organizing technical docs today. Think of it as the ultimate cheat sheet for what to write and where to put it. + +## The Four Types of Technical Writing + +The Diátaxis framework divides documentation into four distinct types, each serving a unique purpose and audience need. + +The four categories are: + +1. **Tutorials (Learning)**: The 'walkthrough' +2. **How-To Guides (Practical)**: The 'instructions' +3. **Reference (Information)**: The 'encyclopedia' +4. **Conceptual (Understanding)**: The 'explanation' + +### 1. Tutorials (Learning) + +The tutorial is where a beginner starts. Its goal is to allow the user to **successfully complete a task** in a controlled, guided environment. + +* **Goal:** Learn how to do something for the **first time**. +* **Tone:** Friendly, encouraging, and highly prescriptive ("Do this, then do that."). +* **Structure:** A sequence of steps that lead to a tangible result. It must be repeatable. +* **Example:** "Setting up your first API connection in 5 minutes," or "How to build a simple To-Do app with our SDK." + +### 2. How-To Guides (Practical) + +How-to guides (also called **Procedural Documentation**) are the bread and butter of your documentation. The user already knows *what* the product is and *why* they need it—they just need to get a specific job done quickly. + +* **Goal:** Solve a **specific, real-world problem** or accomplish a task. +* **Tone:** Direct, action-oriented, and matter-of-fact. +* **Structure:** A short, numbered list of steps that focus on a singular outcome. +* **Example:** "How to reset your password," "How to configure two-factor authentication," or "How to deploy to a staging environment." + +:::tip The Key Difference +A **Tutorial** is for learning. A **How-To Guide** is for doing (and usually re-doing). A tutorial teaches you to fish; a how-to guide tells you where to cast your line today. +::: + +### 3. Reference (Information) + +Reference documentation is the authoritative source of truth. It's not meant to be read from start to finish. It's a technical encyclopedia for when you need a quick, specific fact. + +* **Goal:** Provide **accurate, complete, and low-level detail** on system components. +* **Tone:** Neutral, objective, and dense with facts. +* **Structure:** Highly consistent and predictable (e.g., alphabetically or by hierarchy). +* **Example:** **API documentation** (listing every parameter, data type, and error code), command-line interface (CLI) manuals, or configuration file reference. + +### 4. Conceptual (Understanding) + +Conceptual documentation is the "why" that ties everything together. It helps the reader build a mental model of the product. It explains the high-level architecture, the design decisions, and the *philosophy* behind the product. + +* **Goal:** Explain the **big picture** and provide context. +* **Tone:** Explanatory, analytical, and informative. +* **Structure:** Prose, often using diagrams, metaphors, and analogies. +* **Example:** "An Overview of our Microservices Architecture," "Understanding the Data Model," or "How our Caching Layer Works." + +## The Diátaxis Quadrant + +The magic of this framework is how these four types interlock. No single document type can satisfy every user need, which is why your documentation must contain all four. + +| | **Practical Use** | **Theoretical Use** | +| :--- | :--- | :--- | +| **Goal: Learn** | **1. TUTORIALS** (Get started) | **4. CONCEPTUAL** (Understand the "why") | +| **Goal: Do** | **2. HOW-TO GUIDES** (Complete a task) | **3. REFERENCE** (Look up a specific fact) | + +As a developer writing documentation, you must ask yourself: **"What is the user trying to achieve right now?"** and choose the corresponding format. \ No newline at end of file diff --git a/docs/technical-writer/intro/what-is-technical-writing.mdx b/docs/technical-writer/intro/what-is-technical-writing.mdx new file mode 100644 index 0000000..ae9fe86 --- /dev/null +++ b/docs/technical-writer/intro/what-is-technical-writing.mdx @@ -0,0 +1,70 @@ +--- +title: "What is Technical Writing?" +sidebar_label: "1. What is Technical Writing?" +description: "An introduction and definition of technical writing, focusing on its core purpose and relevance in the software and documentation world." +tags: + [ + technical-writing, + documentation, + intro, + definition, + mdx, + tutorial + ] +keywords: + - technical writing definition + - what is documentation + - technical writer role + - clarity and conciseness + - audience-centered writing +--- + +Welcome! You're here because you've seen the term "Technical Writer" floating around the tech space and want to know what the job actually entails. + +In the simplest terms, **Technical Writing is the art of translating complex information into clear, concise, and accessible language for a specific audience.** + +It’s the crucial bridge between the complex **machinery** of a product (the code, the hardware, the API) and the person who needs to use it (the user, the developer, the internal team). + +--- + +## The Goal: Enable User Success + +Unlike a novelist whose goal is to entertain, or a marketer whose goal is to persuade, the technical writer has one primary mission: **to enable the user to accomplish a specific task successfully.** + +When you're reading documentation, you're not there to enjoy the prose—you're there to **do something**. + +| Quality | What it means | Why it matters | +| :--- | :--- | :--- | +| **Clear** | No ambiguity. The meaning is instantly obvious. | Confusion leads to support tickets and user frustration. | +| **Concise** | Use only the words absolutely necessary. | Developers are busy. Respect their time. Get to the point. | +| **Accurate** | The instructions and facts must be 100% correct. | An inaccurate technical document can break a production system. | +| **Audience-Aware** | Language, tone, and depth are tailored to the reader. | You don't explain a *for-loop* to a senior developer or an *API endpoint* to a non-technical end-user. | + +--- + +## Why Technical Writing Matters (Especially to Developers) + +You might think, "My code is self-documenting!" or "I'll just add a few comments." As a developer, you *already* practice technical writing through commit messages, bug reports, and code comments. Becoming a better technical writer makes you a better developer. + +* **For the End User (Adoption):** Great documentation is a product feature. If a developer can't easily figure out how to integrate your API, they will choose a competitor's. **Good docs drive adoption.** +* **For the Team (Internal Efficiency):** Clear internal documents (like Standard Operating Procedures or Architectural Decision Records) reduce "bus factor," speed up new hire onboarding, and prevent tribal knowledge from disappearing. +* **For Yourself (Problem-Solving):** The act of writing down a complex system or process forces you to identify flaws, contradictions, or gaps in your own understanding. As one developer famously said, "I write code to make the machine happy, and I write documentation to make myself happy." + +## Where Does Technical Writing Live? + +The field is broad, but in the software world, you'll find technical writing in these formats: + +* **API Reference:** Factual, detailed descriptions of endpoints, functions, classes, and parameters. +* **Tutorials and Quickstarts:** Step-by-step guides for first-time use (like this very page!). +* **How-To Guides:** Instructions for specific, real-world tasks ("How to set up SSO," "How to migrate data"). +* **Conceptual/Explanation Guides:** Deep dives into architecture, design choices, and "Why" the product works the way it does. +* **Release Notes:** Summaries of new features, bug fixes, and breaking changes. +* **Tooltips & UI Text:** The tiny bits of text that appear in an application to guide the user (known as **UX writing** or **microcopy**). + +> **In short:** A Technical Writer takes a complicated, specialized topic and makes it universally understandable. They are the empathy engine of the product team. + +--- + +## Next Up + +Now that we know *what* technical writing is, the next step is the most critical: understanding **who** you're writing for. \ No newline at end of file diff --git a/docs/technical-writer/resources/books-and-courses.mdx b/docs/technical-writer/resources/books-and-courses.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/technical-writer/resources/books-and-courses.mdx @@ -0,0 +1 @@ +
+
+ {/* Header Section */}
+
+ );
+};
+
+export default AudiencePersona;
\ No newline at end of file
diff --git a/src/components/AuthorProfile.jsx b/src/components/AuthorProfile.jsx
new file mode 100644
index 0000000..fa5c320
--- /dev/null
+++ b/src/components/AuthorProfile.jsx
@@ -0,0 +1,229 @@
+import React, { useEffect, useState } from "react";
+import {
+ Twitter,
+ Linkedin,
+ Mail,
+ Share2,
+ Copy,
+ Github,
+ Loader2,
+ MessageCircle,
+} from "lucide-react";
+
+/**
+ * AuthorProfile
+ * A responsive two-column author profile component for tutorial pages.
+ * - Left column: GitHub contributor image, name, short bio
+ * - Right column: Social share icons (Twitter, LinkedIn, WhatsApp, Email), copy link
+ *
+ * Props:
+ * - username: (string) GitHub username to fetch avatar and profile URL. Optional.
+ * - name: (string) Fallback / display name.
+ * - bio: (string) Short author bio.
+ * - url: (string) The tutorial URL to share. Defaults to window.location.href when available.
+ * - className: (string) Extra classes for the container.
+ *
+ * Example usage:
+ *
+
+
+ {/* Detail Grid */}
+
+
+
+ {expertise} Expertise
+
+ {name}
+{role}
+
+
+ {/* Goal */}
+
+
+
+
+ {/* Pain Point */}
+
+
+ Goal
+{goal}
+
+
+
+ {/* Needs */}
+
+
+ Pain Point
+{painpoint}
+
+
+
+
+
+ Documentation Needs
+{needs}
+
+
+);
+
+export default function AuthorProfile({
+ username,
+ name,
+ bio,
+ url,
+ className = "",
+}) {
+ const [avatarUrl, setAvatarUrl] = useState(null);
+ const [profileUrl, setProfileUrl] = useState(null);
+ const [loading, setLoading] = useState(Boolean(username));
+
+ useEffect(() => {
+ let cancelled = false;
+ async function fetchGitHub() {
+ if (!username) return setLoading(false);
+ setLoading(true);
+ try {
+ const res = await fetch(
+ `https://api.github.com/users/${encodeURIComponent(username)}`
+ );
+ if (!res.ok) throw new Error("GitHub user not found");
+ const data = await res.json();
+ if (!cancelled) {
+ setAvatarUrl(data.avatar_url);
+ setProfileUrl(data.html_url);
+ }
+ } catch (err) {
+ // silently fallback to initials/avatar placeholder
+ console.warn("AuthorProfile: couldn't fetch GitHub user", err.message);
+ setAvatarUrl(null);
+ setProfileUrl(null);
+ } finally {
+ if (!cancelled) setLoading(false);
+ }
+ }
+ fetchGitHub();
+ return () => (cancelled = true);
+ }, [username]);
+
+ const pageUrl =
+ typeof url === "string"
+ ? url
+ : typeof window !== "undefined"
+ ? window.location.href
+ : "";
+
+ function shareOnTwitter() {
+ const text = encodeURIComponent(
+ `${name || username || "Check this tutorial"}`
+ );
+ const share = `https://twitter.com/intent/tweet?text=${text}&url=${encodeURIComponent(
+ pageUrl
+ )}`;
+ window.open(share, "_blank", "noopener,noreferrer");
+ }
+
+ function shareOnLinkedIn() {
+ const share = `https://www.linkedin.com/sharing/share-offsite/?url=${encodeURIComponent(
+ pageUrl
+ )}`;
+ window.open(share, "_blank", "noopener,noreferrer");
+ }
+
+ function shareOnWhatsApp() {
+ const text = encodeURIComponent(`${name || "Tutorial"} - ${pageUrl}`);
+ const share = `https://wa.me/?text=${text}`;
+ window.open(share, "_blank", "noopener,noreferrer");
+ }
+
+ function shareByEmail() {
+ const subject = encodeURIComponent(`${name || "Tutorial"}`);
+ const body = encodeURIComponent(
+ `I thought you might find this useful: ${pageUrl}`
+ );
+ window.location.href = `mailto:?subject=${subject}&body=${body}`;
+ }
+
+ async function copyLink() {
+ try {
+ await navigator.clipboard.writeText(pageUrl);
+ // subtle feedback: use alert for simplicity (you can replace with a toast system)
+ alert("Link copied to clipboard");
+ } catch (e) {
+ // fallback: select text input
+ prompt("Copy the link:", pageUrl);
+ }
+ }
+
+ return (
+
+
+ );
+};
+
+export default SkillCard;
diff --git a/src/components/ToolCard.module.css b/src/components/ToolCard.module.css
new file mode 100644
index 0000000..943b34d
--- /dev/null
+++ b/src/components/ToolCard.module.css
@@ -0,0 +1,69 @@
+/*
+ * ToolCard.module.css
+ * Styles for the custom
+
+
+
+ + {title} +
++ {description} +
+
+ {/* Card Header for the Tool Name */}
+
+ );
+}
+
+
+// How to use the ToolCard component:
+/*
+
+
+
+ {/* Card Body for Description and Use Case */}
+ {name}
+
+ {/* Description Section */}
+
+ + {description} +
+ + {/* Use Case/Why it matters Section */} +
+
+ + Use Case / Why it Matters: +
++ {useCase} +
+