diff --git a/docs/ai-ml/ai-agents/index.mdx b/docs/ai-ml/ai-agents/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/ai-ml/ai-agents/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/ai-ml/ai-data-scientist/index.mdx b/docs/ai-ml/ai-data-scientist/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/ai-ml/ai-data-scientist/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/ai-ml/ai-engineer/index.mdx b/docs/ai-ml/ai-engineer/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/ai-ml/ai-engineer/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/ai-ml/ai-red-teaming/index.mdx b/docs/ai-ml/ai-red-teaming/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/ai-ml/ai-red-teaming/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/ai-ml/bi-analyst/index.mdx b/docs/ai-ml/bi-analyst/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/ai-ml/bi-analyst/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/ai-ml/data-analyst/index.mdx b/docs/ai-ml/data-analyst/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/ai-ml/data-analyst/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/ai-ml/data-engineer/index.mdx b/docs/ai-ml/data-engineer/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/ai-ml/data-engineer/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/ai-ml/index.mdx b/docs/ai-ml/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/ai-ml/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/ai-ml/machine-learning/index.mdx b/docs/ai-ml/machine-learning/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/ai-ml/machine-learning/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/ai-ml/prompt-engineering/index.mdx b/docs/ai-ml/prompt-engineering/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/ai-ml/prompt-engineering/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/angular/index.mdx b/docs/angular/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/angular/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/aspnet-core/index.mdx b/docs/aspnet-core/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/aspnet-core/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/aws/index.mdx b/docs/aws/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/aws/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/cloudflare/index.mdx b/docs/cloudflare/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/cloudflare/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/code-review/index.mdx b/docs/code-review/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/code-review/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/computer-science/index.mdx b/docs/computer-science/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/computer-science/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/design/design-system/index.mdx b/docs/design/design-system/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/design/design-system/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/design/index.mdx b/docs/design/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/design/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/design/ux-design/index.mdx b/docs/design/ux-design/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/design/ux-design/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/developer-relations/index.mdx b/docs/developer-relations/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/developer-relations/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/devops/index.mdx b/docs/devops/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/devops/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/docker/index.mdx b/docs/docker/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/docker/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/java/index.mdx b/docs/java/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/java/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/kubernetes/index.mdx b/docs/kubernetes/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/kubernetes/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/laravel/index.mdx b/docs/laravel/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/laravel/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/linux/index.mdx b/docs/linux/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/linux/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/management/engineering-manager/index.mdx b/docs/management/engineering-manager/index.mdx new file mode 100644 index 0000000..e69de29 diff --git a/docs/management/index.mdx b/docs/management/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/management/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/management/product-manager/index.mdx b/docs/management/product-manager/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/management/product-manager/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/mongodb/index.mdx b/docs/mongodb/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/mongodb/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/nextjs/index.mdx b/docs/nextjs/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/nextjs/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/rust/index.mdx b/docs/rust/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/rust/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/shell-bash/index.mdx b/docs/shell-bash/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/shell-bash/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/software-architect/index.mdx b/docs/software-architect/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/software-architect/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/software-design-architecture/index.mdx b/docs/software-design-architecture/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/software-design-architecture/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/spring-boot/index.mdx b/docs/spring-boot/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/spring-boot/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/sql/index.mdx b/docs/sql/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/sql/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/swift-ui/index.mdx b/docs/swift-ui/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/swift-ui/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/system-design/index.mdx b/docs/system-design/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/system-design/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/technical-writer/advanced/localization-and-accessibility.mdx b/docs/technical-writer/advanced/localization-and-accessibility.mdx index e345ed2..6392342 100644 --- a/docs/technical-writer/advanced/localization-and-accessibility.mdx +++ b/docs/technical-writer/advanced/localization-and-accessibility.mdx @@ -1 +1,62 @@ - \ No newline at end of file +--- +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. \ No newline at end of file diff --git a/docs/technical-writer/advanced/open-source-contributions.mdx b/docs/technical-writer/advanced/open-source-contributions.mdx index e345ed2..f2eaeeb 100644 --- a/docs/technical-writer/advanced/open-source-contributions.mdx +++ b/docs/technical-writer/advanced/open-source-contributions.mdx @@ -1 +1,83 @@ - \ No newline at end of file +--- +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. \ No newline at end of file diff --git a/docs/technical-writer/advanced/seo-for-documentation.mdx b/docs/technical-writer/advanced/seo-for-documentation.mdx index e345ed2..ad1cad3 100644 --- a/docs/technical-writer/advanced/seo-for-documentation.mdx +++ b/docs/technical-writer/advanced/seo-for-documentation.mdx @@ -1 +1,74 @@ - \ No newline at end of file +--- +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. \ No newline at end of file diff --git a/docs/technical-writer/advanced/technical-writing-career-path.mdx b/docs/technical-writer/advanced/technical-writing-career-path.mdx index e345ed2..afcbc8c 100644 --- a/docs/technical-writer/advanced/technical-writing-career-path.mdx +++ b/docs/technical-writer/advanced/technical-writing-career-path.mdx @@ -1 +1,72 @@ - \ No newline at end of file +--- +title: The Technical Writing Career Path +sidebar_label: "5. Technical Writing Career Path" +description: A practical guide to the technical writing career ladder, covering roles from Associate to Principal, salary expectations, and skills needed for advancement. +--- + +So you've mastered the fundamentals, you know your way around Git, and you can structure a killer API reference. Now what? Technical writing isn't just a job; it's a career with a clear, upward trajectory. + +The path moves beyond just writing documents. As you advance, your role shifts toward **strategy, information architecture, tool ownership, and mentorship.** + +--- + +## The Standard Career Ladder + +While titles vary by company (some use "Content Strategist," others use "Information Developer"), the responsibilities generally progress across three key levels. + +### 1. Associate/Junior Technical Writer (Focus: Execution) + +This is the entry point. You are a content producer, focusing on learning the company's tools, products, and style. + +* **Core Responsibilities:** + * Writing and updating **Tutorials** and **How-To Guides** based on engineer input. + * Fixing bugs and typos in existing documentation. + * Learning the **Git workflow** (committing, merging, opening PRs). + * Attending meetings to gather information (SME interviews). +* **Skills to Develop:** **Time management**, strict adherence to the **Style Guide**, and **active listening** during SME interviews. +* **Goal:** Demonstrate the ability to take a technical concept and turn it into clear, error-free instructions without heavy supervision. + +### 2. Senior Technical Writer (Focus: Ownership and Strategy) + +The senior level is where you take ownership of an entire product line or documentation suite. You are now the expert resource for documentation within your team. + +* **Core Responsibilities:** + * **Information Architecture:** Designing the structure of new documentation (the Diátaxis framework). + * **Tool Ownership:** Managing the documentation platform (e.g., maintaining the Docusaurus setup or managing the CCMS). + * **Review and Editing:** Acting as the primary **style and grammar checker** for junior writers and engineers. + * **Driving Content Strategy:** Identifying content gaps using search analytics (SEO). +* **Skills to Develop:** **Project Management**, **UX Writing** (understanding how content impacts user experience), and **Leadership**. +* **Goal:** Successfully launch and maintain the documentation for a major product or feature with high quality and consistency. + +### 3. Principal Writer / Content Strategist (Focus: Vision and Influence) + +These are the most advanced roles. You don't just execute strategy; you *create* it, influencing the entire organization. + +* **Core Responsibilities:** + * **Defining the Global Style Guide:** Creating and enforcing company-wide style and voice standards. + * **Tool Stack Selection:** Researching and making large-scale decisions about new documentation platforms (e.g., advocating for a CCMS or a new SSG). + * **Mentorship:** Coaching senior and junior writers. + * **Cross-Functional Collaboration:** Working with VP-level product and engineering leaders on long-term strategy and documentation budgets. +* **Skills to Develop:** **Strategic thinking**, **Budgeting**, **Executive communication**, and deep knowledge of **Localization and Accessibility** standards. +* **Goal:** Establish documentation as a first-class citizen within the company, directly tying content goals to business outcomes (like reduced support costs). + +--- + +## Salary and Growth Expectation + +Technical writer salaries are generally excellent, often tracking closely with software developer salaries, especially in technology hubs. The biggest factor influencing your salary is your **specialization** and **technical stack** expertise. + +| Factor | High-Value Specialization | Why It Pays More | +| :--- | :--- | :--- | +| **Industry** | Fintech, AI/ML, Cloud Infrastructure (AWS, Azure). | Requires specialized subject matter expertise (SME) and understanding of compliance/security. | +| **Tooling** | OpenAPI/Swagger, DITA/CCMS, Docusaurus/React. | Proves you can manage complex modern toolchains and automated documentation pipelines. | +| **Content Type** | API Documentation, SDK Guides, Architecture Docs. | These documents directly enable other developers and drive product adoption. | + +### How to Accelerate Your Advancement + +1. **Become a Tool Master:** Don't just *use* Docusaurus; learn how to *configure* and *troubleshoot* it. Understand the **CI/CD pipeline** that publishes your docs. The closer you are to the code, the more valuable you become. +2. **Take Ownership of the Unknown:** Volunteer to document the hardest, least understood parts of the product. That's where you learn the most, and that's where you build credibility with the engineers. +3. **Use Data:** Advocate for documentation changes using **analytics**, not just intuition. Don't say, "I think this section is bad." Say, "Analytics show the bounce rate on this page is 90% because users are searching for X query, but we are providing Y answer." +4. **Teach and Mentor:** As soon as you are comfortable, teach a junior colleague or a new engineer how your documentation system works. Teaching is the best way to solidify your own knowledge and step into a leadership role. + +Your career as a technical writer is what you make it. It starts with writing clarity and ends with strategic influence over how a product communicates with the world. \ No newline at end of file diff --git a/docs/technical-writer/advanced/writing-for-developers.mdx b/docs/technical-writer/advanced/writing-for-developers.mdx index e345ed2..ef1e635 100644 --- a/docs/technical-writer/advanced/writing-for-developers.mdx +++ b/docs/technical-writer/advanced/writing-for-developers.mdx @@ -1 +1,77 @@ - \ No newline at end of file +--- +title: Writing for Developers +sidebar_label: "1. Writing for Developers" +description: "Advanced strategies for creating technical content (APIs, SDKs, Tutorials) that meets the specific needs of engineers—prioritizing code, clarity, and task completion." +--- + +The developer audience is perhaps the most discerning and impatient audience you will face. They are highly technical, highly task-oriented, and have an immediate, specific goal: **make the code work.** + +Your documentation should be treated as another tool in their kit—it must be functional, accurate, and optimized for speed. + +## 1. The Mindset: Goal-Oriented Documentation + +Forget the traditional structure of a book. Developer documentation must be structured around what the engineer is trying to **achieve**. + +The most effective documentation follows the **Diátaxis Framework**, which categorizes content into four essential types: + +| Type | Goal | Question it Answers | Use Case | +| :--- | :--- | :--- | :--- | +| **Tutorials** | Learning (Getting Started) | **How do I do X?** | A step-by-step guide to achieve a tangible, working result (e.g., "Build your first 'Hello World' app with our SDK"). | +| **How-To Guides** | Doing (Problem Solving) | **How do I achieve this specific task?** | Recipes for common, real-world tasks (e.g., "Configure OAuth 2.0 authentication," "Handle a 429 Rate Limit error"). | +| **Reference** | Information (The Facts) | **What is X, and what are its parameters?** | The exhaustive, technical specification for every function, endpoint, or class (e.g., API reference tables). | +| **Explanation** | Understanding (Context) | **Why does X exist?** | High-level context and architectural overviews (e.g., "Why we chose a microservices architecture," "Overview of the data model"). | + +:::tip Time-to-First-Successful-Call (TTFSC) +The primary metric for a developer's first experience is the TTFSC. Your **Tutorials** must be ruthlessly optimized to get the user a working result in the minimum number of steps. Reduce friction by making code **copy-pastable** and assumptions **explicit**. +::: + +## 2. Prioritizing Code and Examples + +Code is the universal language of developers. Your text is secondary to the code examples you provide. + +* **Copy-Paste Ready:** Every code snippet—from the `curl` request to the Python client—must be tested and designed to be copied directly into the terminal or IDE. No manual edits should be necessary unless explicitly noted (e.g., replacing an API key). +* **The Request/Response Block:** For API documentation, the request and response samples are the most critical elements. Show: + 1. The complete **Request** (method, URL, headers, and body). + 2. The complete **Response** for a successful `200 OK` call. + 3. A sample **Error Response** (e.g., `400 Bad Request` or `401 Unauthorized`) with clear JSON error messages for debugging. +* **Language Variety:** If your SDK supports multiple languages (Python, Node.js, Go), provide examples for the most common languages your audience uses. Use tabs or conditional content to keep the page clean. + +```json title="example_response.json" +{ + "status": "success", + "data": { + "widgetId": "wg_1923847", + "name": "SuperWidget", + "is_enabled": true + } +} +``` + +## 3. The Power of Reference Tables + +Engineers rely on tables to quickly find a fact or confirm a detail. Design your reference documentation for **scanning**, not reading. + +For API endpoints or function parameters, always use a table with four consistent columns: + +| Parameter/Field | Data Type | Required? | Description | +| :--- | :--- | :--- | :--- | +| `widget_id` | `string` | **Yes** | The unique identifier for the widget being modified. | +| `new_status` | `integer` | No | New state of the widget: `0` for inactive, `1` for active. Defaults to `0`. | +| `auth_token` | `string` | **Yes** | **(Header)** OAuth token required for authentication. Must be type **Bearer**. | + +## 4\. The Developer-Friendly Tone + +Developers value **authenticity, accuracy, and efficiency**. Your tone should reflect this: + + * **Be Direct and Imperative:** Use active voice and tell the user exactly what to do. + * **Good:** "Run this command." "The function returns a Promise." + * **Bad:** "You may consider running this command." "A Promise is returned by the function." + * **Acknowledge Complexity:** It's okay to say something is complex or difficult. Use **Warnings** and **Notes** to flag potential pitfalls. + + :::warning + Generating and managing OAuth tokens is often the trickiest part of integration. Verify your scopes carefully. + ::: + + * **Avoid Marketing Fluff:** Cut all corporate buzzwords, excessive adjectives, and vague promises. Get straight to the technical utility. **The documentation should state what the code does, not how great the company is.** + + * **Respect the User's Time:** Developers are goal-oriented and impatient. Keep explanations concise and to the point. Use bullet points, numbered steps, and code blocks to facilitate quick comprehension. \ 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 index e345ed2..2e50144 100644 --- a/docs/technical-writer/resources/books-and-courses.mdx +++ b/docs/technical-writer/resources/books-and-courses.mdx @@ -1 +1,103 @@ - \ No newline at end of file +--- +title: Books and Courses for Technical Writers +sidebar_label: "1. Books and Courses" +description: A curated list of essential books, courses, and resources to help technical writers advance their skills in documentation, API writing, and career development. +--- + +import LinkCard from '@site/src/components/LinkCard'; +import SkillCard from '@site/src/components/SkillCard'; +import { FaBook, FaGlobe, FaCode, FaGraduationCap } from 'react-icons/fa'; + +The best technical writers are lifelong learners. The tools, platforms, and even the programming languages change constantly, but the foundational principles of clarity and audience focus remain constant. + +Here is a curated list of resources to help you deepen your skills in specialized areas, from content strategy to hands-on tooling. + +--- + +## 1. Essential Foundational Books + +These texts are widely recognized as foundational reading for professional technical writers, offering timeless principles on grammar, style, and structure. + +
+ } + /> + } + /> + } + /> + } + /> +
+ +--- + +## 2. Recommended Online Courses + +For hands-on learning and practical application of tools, online courses offer structured paths to specialized skills. + +### A. API Documentation + +Mastering API documentation is a high-value skill that often commands higher salaries. These courses dive deep into specification languages and tooling. + + + +### B. Docs-as-Code Tooling + +To successfully integrate with engineering teams, you must be comfortable with the command line and version control. + + + +### C. Content Strategy and Information Architecture + +For senior writers, understanding how to structure and govern large documentation sets is key. + + + +--- + +## 3. Essential Online Style Guides + +You don't need to buy a book for basic style rules. Always keep these public guides bookmarked: + +* **Google Developer Documentation Style Guide:** (Free) Excellent for code examples, API reference, and general tone for a developer audience. +* **A List Apart:** While not a style guide, this resource offers deep dives into content strategy, web writing, and usability. +* **The Write the Docs Glossary:** A great, community-maintained resource for quickly looking up technical writing jargon and industry terms. + +--- + +## 4. The Best Resource: Community + +The single most valuable resource in technical writing is the community. + +* **Write the Docs:** The largest and most active technical writing community. They host conferences, run local meetups, and maintain an extremely helpful Slack channel. +* **Reddit (r/technicalwriting):** A great source for career advice, tooling debates, and finding answers to common problems. +* **Local Meetups:** Search for local technical writing, documentation, or user assistance groups in your area for in-person networking. + +By engaging with these resources, you ensure your skills are always current, relevant, and in demand. \ No newline at end of file diff --git a/docs/technical-writer/resources/communities-and-blogs.mdx b/docs/technical-writer/resources/communities-and-blogs.mdx index e345ed2..dc9fdff 100644 --- a/docs/technical-writer/resources/communities-and-blogs.mdx +++ b/docs/technical-writer/resources/communities-and-blogs.mdx @@ -1 +1,72 @@ - \ No newline at end of file +--- +title: Communities and Blogs +sidebar_label: "2. Communities and Blogs" +description: "A curated list of the most active professional communities, blogs, and social hubs where technical writers connect, share knowledge, and find job opportunities." +--- + +import LinkCard from '@site/src/components/LinkCard'; + +Technical writing can sometimes feel like a solo job, but you are part of a huge, global community! Staying connected is crucial for finding job opportunities, solving tooling dilemmas, and keeping up with the rapid pace of change in the tech industry. + +--- + +## 1. The Must-Join Professional Community: Write the Docs + +**Write the Docs (WTD)** is the largest and most influential community dedicated to people who write, illustrate, and design documentation. It is the single best resource for continuous professional development. + + + +### The Write the Docs Slack Workspace + +The WTD Slack is where the daily conversation happens. You can join channels dedicated to specific topics, making it easy to get real-time help. + +* **#tools:** Ask questions about Docusaurus, Sphinx, Markdown, or version control. +* **#jobs:** The primary channel for finding new technical writing positions and contract work. +* **#beginners:** A safe space for new writers to ask foundational questions without judgment. +* **#style-guides:** Discussing the pros and cons of Google vs. Microsoft style rules. + +## 2. Social Hubs and Discussion Forums + +These platforms are excellent for quick questions, career advice, and engaging in broader professional discussions. + +
+ + +
+ +## 3. Key Blogs and Publications + +Following leading figures and documentation teams ensures you stay current on best practices, emerging tools, and content strategy trends. + +### The Google Developer Documentation Blog + +This is a gold standard resource. The Google dev docs team often publishes articles on their processes, style guide updates, and high-level strategy for managing massive documentation sets. Following their work is a great way to elevate your own standards. + +### Specialized Docs Tooling Blogs + +Follow the blogs of the tools you use, as they often announce new features and best practices: + +* **Docusaurus:** Follow their releases for the latest features like MDX component support and theme updates. +* **GitLab/GitHub Documentation:** These platforms constantly innovate in the Docs-as-Code space. Pay attention to how they structure and release their own documentation. + + + +--- + +By actively engaging in these communities, you transition from someone who *writes* documentation to someone who *is* a professional in the field, opening up mentorship, collaboration, and career opportunities. \ No newline at end of file diff --git a/docs/technical-writer/resources/portfolio-building.mdx b/docs/technical-writer/resources/portfolio-building.mdx index e345ed2..e5ea391 100644 --- a/docs/technical-writer/resources/portfolio-building.mdx +++ b/docs/technical-writer/resources/portfolio-building.mdx @@ -1 +1,93 @@ - \ No newline at end of file +--- +title: Portfolio Building +sidebar_label: "4. Portfolio Building" +description: "Step-by-step guide on how to build a professional, high-impact technical writing portfolio that demonstrates mastery of modern tools and documentation standards." +--- + +import LinkCard from '@site/src/components/LinkCard'; + +Your portfolio is your professional calling card. It’s what hiring managers and recruiters look at **first**, often before they even read your resume. A strong portfolio doesn't just show your writing; it demonstrates your mastery of the entire **Docs-as-Code workflow**. + +## 1. What a Modern Portfolio Must Demonstrate + +A hiring manager needs proof of three things. Your portfolio should explicitly showcase all of them. + +### A. Technical Proficiency (The Tools) + +You must prove you can work in a modern engineering environment. + +* **GitHub/GitLab:** All your projects should be hosted in a **public Git repository**. This proves you understand version control, branching, and pull requests. +* **Modern Tooling:** Your portfolio site itself should be built using a **Static Site Generator (SSG)** like Docusaurus, MkDocs, or Hugo. This shows you can handle the command line and modern publishing workflows. +* **Code Samples:** Demonstrate comfort with **Markdown, JSON, XML, and code blocks** with proper syntax highlighting. + +### B. Writing and Clarity (The Content) + +You need to show you can adapt your voice to different audiences. + +* **Task-Orientation:** The documentation should guide the user to a successful outcome (a finished task). +* **Clarity and Conciseness:** No fluff, no marketing jargon. Just clear, unambiguous instructions. +* **Style Guide Adherence:** Use consistent formatting, terminology, and tone. + +### C. Information Architecture (The Structure) + +You must prove you can organize complex information. + +* **Navigational Structure:** Show that you can structure a sidebar logically and use cross-linking effectively. +* **Content Hierarchy:** Use clear headings (H2, H3) and lists to break down text for scannability. + +--- + +## 2. Essential Portfolio Projects (The Core Four) + +Aim for 3–5 high-quality projects. A few excellent, polished examples are infinitely better than ten mediocre ones. + +| Project Type | Skill Demonstrated | Example Topic Idea | +| :--- | :--- | :--- | +| **1. API Reference** | Writing for developers, structured data (JSON/YAML), tables, request/response. | Document a public API (e.g., NASA, OpenWeatherMap, a cryptocurrency exchange). | +| **2. Setup/How-To Guide** | Task-oriented writing, numbered lists, prerequisites, troubleshooting, visual aids. | How to set up a Docker container, how to configure a simple serverless function, or how to run a React app locally. | +| **3. Conceptual Explanation** | Explaining complex concepts simply, analogies, diagrams, high-level overviews. | Explain "What is OAuth 2.0?" or "How does a CDN work?" for a non-technical manager. | +| **4. Release Notes/Changelog** | Conciseness, categorizing changes, identifying user value. | Write a sample set of release notes for the latest update of a popular app (e.g., Slack, VS Code). | + + + +--- + +## 3. Step-by-Step Guide to Building Your Site + +Follow this simple, professional workflow for creating your portfolio site: + +### Step 1: Choose Your Platform + +Build your portfolio using a modern SSG. **Docusaurus** is a great choice because it's built for documentation and handles sidebars, navigation, and search out of the box. + +### Step 2: Create a Repository + +1. Create a new public repository on **GitHub** (e.g., `my-portfolio-docs`). +2. Commit all your project files (Markdown, config, images) here. +3. Use the `main` branch only for the live content. + +### Step 3: Write Your Projects + +Use the core four types listed above. For each project: + +* Create a separate Markdown file (`api-reference.mdx`, `docker-setup.mdx`). +* Ensure every file has a clear front matter (`title`, `description`, `slug`). +* Embed sample code blocks and **screenshots** (use placeholders if you can't generate actual UIs). + +### Step 4: Add Context and Links + +* **The "About Me" Section:** Include a short, professional paragraph explaining your technical background and specific skill set (e.g., "Experienced in documenting cloud APIs and CI/CD pipelines"). +* **The Live Links:** For every project, clearly link to: + 1. The **Live Documentation Page** (e.g., `yourname.github.io/portfolio/api-reference`). + 2. The **Source File** on GitHub (e.g., `github.com/yourname/my-portfolio-docs/api-reference.mdx`). This shows transparency and Git mastery. + +### Step 5: Get Feedback + +Share your portfolio link with other technical writers (e.g., in the Write the Docs Slack). Ask them specific questions: Is the navigation confusing? Did the code sample work? Is the tone consistent? + +A portfolio that shows off your writing and your ability to use modern tools will set you apart from 90% of the competition. \ No newline at end of file diff --git a/docs/technical-writer/resources/templates-and-samples.mdx b/docs/technical-writer/resources/templates-and-samples.mdx index e345ed2..0492adb 100644 --- a/docs/technical-writer/resources/templates-and-samples.mdx +++ b/docs/technical-writer/resources/templates-and-samples.mdx @@ -1 +1,177 @@ - \ No newline at end of file +--- +title: Templates and Samples +sidebar_label: "3. Templates and Samples" +description: "Ready-to-use templates and structural samples for common documentation types, including API Reference, Release Notes, and Step-by-Step Guides." +--- + +import LinkCard from '@site/src/components/LinkCard'; +import SkillCard from '@site/src/components/SkillCard'; +import { FaFileCode, FaClipboardList, FaBullhorn, FaBook } from 'react-icons/fa'; + +Starting a new document from a blank page is the hardest part. The templates below provide a proven structural foundation for the most common types of technical documentation, ensuring you hit all the necessary points right from the start. + +Use these as boilerplate to focus immediately on the content, not the formatting. + +--- + +## 1. API Reference Endpoint Template (Markdown/MDX) + +This structure is ideal for documenting a single, specific endpoint (e.g., `POST /v1/users`). It ensures all required details for a developer are immediately visible. + +} +/> + + +````markdown +--- +title: POST /v1/resource +--- + +## Endpoint: Create a New Resource + +### Description +Creates a new [Resource Name] object in the system. Use this endpoint to initialize new data structures. + +### Request Details +| Field | Value | +| :--- | :--- | +| **Method** | `POST` | +| **URL** | `https://api.example.com/v1/resource` | +| **Authentication** | Required (Bearer Token in Header) | +| **Rate Limit** | 100 requests per minute | + +### Request Parameters (Body: JSON) +| Parameter | Type | Required | Description | +| :--- | :--- | :--- | :--- | +| `name` | `string` | Yes | The user-friendly name of the resource. | +| `settings.config_id` | `integer` | No | Optional configuration ID to apply. Defaults to 0. | + +### Request Example (cURL) +```bash +curl -X POST 'https://api.example.com/v1/resource' \ + -H 'Authorization: Bearer [YOUR_TOKEN]' \ + -H 'Content-Type: application/json' \ + -d '{ + "name": "New Project Widget", + "settings": { "config_id": 10 } + }' +``` + +### Response Codes + +| Code | Status | Description | +| :--- | :--- | :--- | +| **201** | Created | The resource was created successfully. | +| **400** | Bad Request | The required `name` field was missing. | +| **401** | Unauthorized | Invalid or expired Bearer Token provided. | + +### Successful Response Example (201) + +```json +{ + "status": "success", + "data": { + "resource_id": "res_a01b2c", + "status": "pending_setup" + } +} +``` + +```` + +--- + +## 2. Release Notes Template (Structured for Scanning) + +This template prioritizes categorized lists and concise language, ensuring users can find new features or bug fixes in seconds. + +} +/> + +````markdown +# Release Notes: Version X.Y.Z (Released Month Day, Year) + +This release focuses on improving dashboard performance and introducing a highly requested Dark Mode theme. + +## New Features and Enhancements + +* **Dark Mode Theme:** Users can now switch to a comfortable dark viewing experience under **Settings > Display**. +* **Faster Loading:** Optimized asset loading reduces the initial dashboard load time by 35%. +* **Enhanced API Filtering:** The `/reports` API endpoint now supports filtering by resource status. + +## Fixed Bugs + +* Resolved an issue where saved reports would sometimes display data from the previous user session. +* Fixed a bug that prevented the **Export to CSV** button from being clickable on mobile devices. +* Corrected a styling error causing overlapping text in the "Help" section sidebar. + +## Known Issues and Workarounds + +* **Issue:** The real-time activity feed may briefly disconnect when changing network connections. +* **Workaround:** Simply refresh the page to restore the connection. We are actively working on a fix for version X.Y.Z+1. +```` + +----- + +## 3. Step-by-Step Procedure Guide Template + +The essential template for any **How-To Guide** or **Tutorial** (Task-Oriented Content). + +} +/> + +````markdown +# How to [Achieve a Specific Goal] + +This guide walks you through the steps required to [Goal/Outcome]. This typically takes [X minutes]. + +## Prerequisites + +* You must have **Admin** privileges on the account. +* The system requires [Software/Tool] version X.0 or higher. + +## Procedure + +1. **Navigate** to the main Dashboard page. +2. In the top navigation bar, **click** the **Settings** icon (gear). +3. From the Settings menu, **select** **System Configuration**. + * *Note: If you do not see this option, your user role may be insufficient.* +4. **Enter** the required value (`my-app-id`) into the field labeled **Application ID**. +5. **Click** the **Apply Changes** button at the bottom of the page. + + +## Verification + +To verify your changes, [describe a simple check the user can perform]. For example, refresh the Dashboard and look for the new indicator lights to turn green. +```` + +----- + +## 4. External Template Resources + +For more comprehensive templates and structural frameworks, check out these external resources that often provide full repository examples. + + + + + +This collection of templates should help you get started quickly on your documentation projects, ensuring clarity and consistency across your work. \ No newline at end of file diff --git a/docs/technical-writer/tools/docs-platforms.mdx b/docs/technical-writer/tools/docs-platforms.mdx index e345ed2..9eebb8b 100644 --- a/docs/technical-writer/tools/docs-platforms.mdx +++ b/docs/technical-writer/tools/docs-platforms.mdx @@ -1 +1,133 @@ - \ No newline at end of file +--- +title: Documentation Platforms and Static Site Generators +sidebar_label: "2. Docs Platforms" +tags: ["technical-writing", "tools", "documentation-platforms", "static-site-generators"] +description: "An overview of the tools and platforms technical writers use to manage, build, and deploy documentation, focusing on static site generators like Docusaurus and MkDocs." +--- + +Once you've written your brilliant Markdown (`.mdx`) files, you need a system to turn that plain text into a beautiful, searchable website. This system is typically a **Documentation Platform** or a **Static Site Generator (SSG)** tailored for docs. + +## The Shift: From Word Processors to Code + +A key difference in modern technical writing is that your documentation is treated like code. It's stored in a repository, built by a program, and deployed via automation. This offers huge benefits in speed, consistency, and collaboration. + +### The Two Main Approaches + +| Platform Type | Description | Best For | Examples | +| :--- | :--- | :--- | :--- | +| **SaaS/Cloud Platforms** | All-in-one solutions that handle editing, hosting, and publishing entirely within a web interface. Less setup, less customization. | Small teams, non-technical writers, and rapid deployment. | Confluence, ReadMe, Help Scout | +| **Static Site Generators (SSGs)** | Programs that take your source files (Markdown, images) and convert them into simple HTML/CSS/JS files, which are fast and cheap to host. | Developers, technical writers, open-source projects, and high customization needs. | Docusaurus, Next.js, Hugo, MkDocs | + +:::tip Why SSGs? +SSGs are the darlings of modern tech documentation because they are incredibly fast, highly secure (since they generate no server-side code), and align perfectly with development workflows (Git). +::: + +## Deep Dive: Key SSG Features for Technical Docs + +When choosing an SSG (like the one running **CodeharborHub**), look for these critical features designed specifically for documentation: + +### 1. Versioning (The Time Machine) + +The most vital feature. Products change quickly, but your users need documentation for the version they are *currently* using. + +* **Concept:** Allows you to freeze the state of your documentation for a specific product version (e.g., v1.0, v2.0). +* **User Impact:** A user on an older product version can view accurate, corresponding instructions without seeing features that don't exist yet. +* **How it Works:** The SSG manages separate directories for each version (e.g., `docs/v1.0`, `docs/v2.0`). + +### 2. Search (The North Star) + +If users can't find it, it doesn't exist. Effective documentation platforms integrate powerful, full-text search. + +* **Local Search:** Some small SSGs use client-side search (using only JavaScript). +* **External Search:** Most professional sites use dedicated indexing services (like Algolia or ElasticSearch) that integrate seamlessly into the platform's UI. This is usually faster and more accurate. + +### 3. Navigation and Structure + +A good platform automatically manages the relationship between your files and the site structure. + +* **Sidebar Generation:** Creates the hierarchical sidebar based on your file structure and a simple configuration file (`_sidebar.yml` or similar). +* **Table of Contents (TOC):** Automatically generates the right-hand TOC based on your `H2`, `H3`, and `H4` headings within a Markdown file, making long pages digestible. + +### 4. Custom Components (MDX) + +As a technical writer, you'll often need more than just text. MDX allows you to embed interactive elements: + +* **Tabs:** Displaying code snippets in different languages (e.g., JavaScript, Python) that a user can switch between. +* **Callouts/Admonitions:** Custom blocks for `Note`, `Warning`, `Tip`, and `Danger` that look better than standard blockquotes. + +```markdown title="Callout Example in a tool like Docusaurus" +:::tip +Remember to clear your cache after updating the firmware! +::: +``` + +:::info Static Site Generators (SSGs) + +
+ +SSGs are the **developer's choice**. They compile your content into static HTML, CSS, and JavaScript files during a "build" process. The resulting site is incredibly fast, secure, and easily version-controlled. + +| Feature | Description | Best For | Examples | +| :--- | :--- | :--- | :--- | +| **Content Format** | Markdown (MDX) | **Engineers** writing documentation alongside code. | Docusaurus (React-based, great for versioning), MkDocs (Python/simple), Jekyll (Ruby/GitHub Pages). | +| **Pros** | **Speed** (lightning fast), **Security** (no server-side database), **Cost-effective** (often free to host). | Companies with **GitHub/Git workflow maturity** and developers willing to manage the setup. | Docusaurus, MkDocs, Hugo | +| **Cons** | **Setup complexity** (requires Node.js, Python, or Go knowledge), **No built-in editor** (you edit in Markdown files). | Writers with **minimal coding experience** or teams needing an editor. | | + +**Why SSGs ?** + +Static sites are the standard for modern API and product documentation because they integrate perfectly with the development team's existing Git workflow. Your documentation is treated as code (**Docs-as-Code**). + +::: + +## Deployment: From Localhost to Live Site + +The final step is getting your documentation online. This is where the "Static" part of SSG shines. + +1. **Local Build:** You run a command (e.g., `npm run build` or `mkdocs build`). +2. **Asset Generation:** The SSG processes your Markdown and creates a folder full of `.html`, `.css`, and `.js` files. +3. **Hosting:** You upload that entire folder to a web server (like Netlify, Vercel, or GitHub Pages). Since there's no server-side processing, the hosting is simple, fast, and secure. + +:::info Hosted, Cloud-Based Solutions + +These platforms provide a full, all-in-one service: the editor, the hosting, and the search functionality. They are designed to get documentation live quickly with minimal setup. + +| Feature | Description | Best For | Examples | +| :--- | :--- | :--- | :--- | +| **Content Format** | Web Editor (WYSIWYG or Markdown) | **Small teams** or companies prioritizing speed-to-market and simplicity. | Document360, Help Scout, Zendesk Guide, GitBook. | +| **Pros** | **Zero setup/maintenance**, **Built-in authoring tools** (no local environment needed), **Excellent collaboration** and permissions. | Teams where technical writers and support agents co-author and non-technical stakeholders must contribute. | GitBook, Document360 | +| **Cons** | **Vendor lock-in** (content lives on their servers), **Less customization** of the final design/UI. | Teams with **strict design requirements** or complex data integration needs. | | + +**Why Hosted Solutions?** + +Hosted documentation platforms are ideal for teams that want to focus on content creation without worrying about the technical aspects of site generation and deployment. They offer a user-friendly interface and built-in features that streamline collaboration and publishing. + +::: + +## Component Content Management Systems (CCMS) & Headless CMS + +These are the enterprise solutions, built for extreme scale, content reuse, and complex workflows. + +### A. CCMS (Component CMS) + +CCMS tools like **Paligo** or **MadCap Flare** focus on **Single-Sourcing** and **Topic-Based Authoring (DITA)**. This means you write small, reusable topics that are pulled into different documents. + +* **Best For:** Manufacturing, Aerospace, Finance, or any environment with high regulatory needs, complex product families, or extreme language/localization requirements. + +### B. Headless CMS + +A Headless CMS (**Contentful, Strapi**) is purely a content repository—it provides the "body" of the content via an API, but no "head" (frontend website). + +* **Best For:** Companies needing to publish the **same content** to a website, a mobile app, and a chatbot simultaneously (omnichannel delivery). The content is authored once and pulled into multiple frontends. + +:::tip Choosing Your Platform: Key Questions + +
+ +| Question | SSG (Docusaurus/MkDocs) | Hosted (GitBook/Document360) | CCMS (Paligo/Flare) | +| :--- | :--- | :--- | :--- | +| **What is your budget?** | Low (free software, pay for simple hosting). | Mid-High (per-user subscription fees). | Very High (significant annual enterprise license). | +| **Who will be writing/contributing?** | Developers and Technical Writers (Markdown). | Anyone (simple web editor). | Technical Writers and Subject Matter Experts. | +| **Do you need versioning (v1.0, v2.0)?** | Yes, **Native and excellent.** | Yes, usually good, sometimes an add-on. | Yes, **Essential and core functionality.** | +| **Do you need extreme content reuse?** | Possible, but requires complex template logic. | Limited, typically page-by-page. | **Yes, this is their core purpose.** | + +::: diff --git a/docs/technical-writer/tools/markdown-basics.mdx b/docs/technical-writer/tools/markdown-basics.mdx index e345ed2..2efc1de 100644 --- a/docs/technical-writer/tools/markdown-basics.mdx +++ b/docs/technical-writer/tools/markdown-basics.mdx @@ -1 +1,124 @@ - \ No newline at end of file +--- +title: Markdown Basics +sidebar_label: "1. Markdown Basics" +description: "Learn the fundamental syntax and structure of Markdown (MDX) to efficiently write, format, and maintain technical documentation across modern platforms." +--- + +Markdown is a lightweight, easy-to-read markup language that technical writers use to format text using a plain text editor. Its design goal is to allow people to write using an easy-to-read, easy-to-write format, and then convert it to structurally valid HTML (or other formats). + +For technical writers, Markdown is essential because it keeps the focus on **content structure** rather than decorative styling. + +## The Core Concept: Structure, Not Style + +Think of Markdown not as a word processor, but as a system for defining document structure. + +* A `#` is not a huge font; it is a **Heading 1**. +* A `*` is not a bold font; it denotes **strong emphasis**. + +When you write in Markdown, the structure is preserved, and the styling (font, color, spacing) is handled later by a **Stylesheet (CSS)**, often provided by your documentation tool (Docusaurus, GitBook, etc.). + +## Essential Markdown Syntax + +Mastering a few simple symbols is all it takes to handle 90% of your documentation needs. + +### 1. Headings (Creating Hierarchy) + +Headings are critical for document navigation and SEO. Markdown uses the hash symbol (`#`) to denote hierarchy. Always skip H1 after the main title. + +| Markdown Syntax | Output/Meaning | Best Practice Use | +| :--- | :--- | :--- | +| `## Section Header` | Heading 2 (H2) | Major sections of your document. | +| `### Subsection Header` | Heading 3 (H3) | Logical divisions within a major section. | +| `#### Topic Detail` | Heading 4 (H4) | Specific topics or steps in a procedure. | +| `# Title of Document` | Heading 1 (H1) | Reserved for the document's main title (often generated automatically by MDX). | + +### 2. Text Formatting (Emphasis) + +Use these sparingly—bolding should guide the user's eye to key terms (like interface elements). + +| Markdown Syntax | Output/Meaning | Best Practice Use | +| :--- | :--- | :--- | +| `**Bold Text**` or `__Bold Text__` | **Bold Text** (Strong Emphasis) | Highlighting interface elements (`Click **Save**`), warnings, or keywords. | +| `*Italic Text*` or `_Italic Text_` | *Italic Text* (Emphasis) | Highlighting book titles, file names, or new terminology. | + +### 3. Lists (The Technical Writer's Best Friend) + +Lists are how you break down complex information. Use numbered lists for sequences and bulleted lists for non-sequential items. + +#### **1. Ordered (Numbered) Lists** +Used for **procedures, steps, or ranked items**. The number you use doesn't matter; Markdown will render the sequence correctly. + +```markdown +1. First step in the process. +1. Second step (Markdown handles the numbering). + 1. A sub-step indented by four spaces or one tab. +``` + +#### **2. Unordered (Bulleted) Lists** + +Used for **features, prerequisites, or collections** where the order doesn't matter. + +```markdown +* Feature A +* Feature B + * Detail of Feature B +* Feature C +``` + +### 4. Code and Terminal Commands + +This is essential for any technical content. Markdown offers two ways to handle code: + +| Markdown Syntax | Use Case | Example | +| :--- | :--- | :--- | +| **Inline Code** | Highlighting a variable, a command, or a file name within a sentence. | Type `npm install` in your terminal. | +| **Code Blocks** | Displaying larger snippets of code, configuration files, or command output. | Wrap the code in three backticks (\`\`\`) and specify the language for syntax highlighting. | + +````markdown title="JavaScript Code Block Example" +```javascript +function calculate(x) { + return x * 2; +} +``` +```` + +### 5. Links and Images (Connecting the Docs) + +Documentation lives and dies by its links. + +#### **1. Links** +The format is simple: `[Text to Display](URL/Path)`. + +```markdown title="Link Examples" +// External Link +[Visit Google](https://www.google.com) + +// Internal Link (Relative Path is Common in MDX) +[Installation Guide](../installation/setup.md) +``` + +#### **2. Images** + +Images follow the same link syntax, but are prefixed with an exclamation mark (`!`). + +```markdown title="Image Example" +![Alternative text for accessibility](path/to/image.png) +``` + +### 6. Blockquotes and Callouts + +Blockquotes (`>`) are often used to highlight notes, definitions, or warnings in documentation systems. + +```markdown +> This is a Blockquote. +> Use it for important notes, warnings, or caution statements. +``` + +## Why Markdown is Better for Technical Writing + +1. **Version Control (Git/GitHub):** Unlike binary files (like `.doc` or `.pdf`), Markdown files are plain text, making them easy to track, compare, and merge using Git. This is foundational for collaborative documentation. +2. **Conversion:** Markdown can be instantly converted to beautiful HTML, PDFs, and even EPUB formats using automation tools. +3. **Future-Proofing:** It uses simple ASCII characters, ensuring your content will be readable on any system, decades from now. +4. **MDX (Markdown + JSX):** Many modern documentation frameworks use MDX, which allows you to embed interactive UI components (like live code editors or custom warnings) directly within your Markdown file, combining simplicity with modern web functionality. + +This guide covers the essentials, but Markdown has many more features to explore. As you become more comfortable, you'll find that Markdown empowers you to create clear, structured, and maintainable technical documentation efficiently. \ No newline at end of file diff --git a/docs/technical-writer/tools/style-guides.mdx b/docs/technical-writer/tools/style-guides.mdx index e345ed2..7885882 100644 --- a/docs/technical-writer/tools/style-guides.mdx +++ b/docs/technical-writer/tools/style-guides.mdx @@ -1 +1,79 @@ - \ No newline at end of file +--- +title: Style Guides for Technical Writers +sidebar_label: "5. Style Guides" +description: "Understand the necessity of style guides, the difference between internal and external guides, and how to apply rules for professional, unambiguous technical communication." +--- + +A **Style Guide** is a set of standards for the writing and design of documents. It's the central authority that dictates everything from capitalization and hyphenation to tone and grammar. + +If the documentation set feels cohesive, professional, and easy to read, you can bet there's a good style guide behind it. Its primary function is to eliminate ambiguity and enforce **consistency** across all authors and documents. + +## Why Consistency is Crucial in Tech Docs + +For creative writers, variety is a virtue. For technical writers, it is a liability. + +| Inconsistent Style | Consistent Style (from a Guide) | Impact on the User | +| :--- | :--- | :--- | +| Use **Log In**, **login**, and **Log-in** randomly. | Always use **Log in** (verb) and **login** (noun/adjective). | Confusion, distraction, and perceived lack of quality control. | +| Refer to the user as "we" or "they." | Always use the direct **"you"** and the imperative mood. | Focuses the user on the action they must take, reducing cognitive load. | +| **API** vs. **Api** vs. **A.P.I.** | Always capitalize the full acronym: **API**. | Ensures the term is recognized instantly and consistently. | + +A style guide frees the writer from making hundreds of minor editorial decisions, allowing them to focus on explaining complex concepts clearly. + +## Major Categories of Style Guides + +Technical writers typically work with two types of style guides: + +### 1. General Linguistic Style Guides (External) + +These guides define the fundamental rules of grammar, mechanics, and syntax. They are often adopted from major external authorities to avoid reinventing the wheel. + +| Guide Name | Focus | Core Principles for Tech Writers | +| :--- | :--- | :--- | +| **Microsoft Writing Style Guide** | Software, IT, and user interface text. | Excellent guidance on voice, tone, and writing for international audiences. Emphasizes clarity and conciseness. | +| **Google Developer Documentation Style Guide** | API documentation, tutorials, and developer-focused content. | Strong rules for code formatting, imperative voice, and handling technical concepts. | +| **Chicago Manual of Style (CMOS)** | Traditional publishing, citations, and formal academic text. | Used for long-form reports or books, particularly for citation and reference formatting. | + +### 2. Product and Brand Style Guides (Internal) + +These guides are unique to your company and product. They define proprietary terminology and the specific voice the company wants to project. + +#### **A. Terminology and Glossary** +This is the most important section for a technical writer. It contains the approved spellings and usage for product features. + +* **Example:** Is it "CodeharborHub," "CodeHarborHub," "Code Harbor Hub" or "Codeharbor Hub?" The guide must specify. + +#### **B. Voice and Tone** +This defines the emotional aspect of your writing. Should your documentation be formal and academic, or conversational and witty? + +* **Formal Tone:** "The application necessitates user authentication prior to resource access." +* **Conversational Tone:** "You must log in to access your files." + +#### **C. UI Element Rules** +How do you refer to elements the user sees on the screen? + +* **Rule:** **Bold** interface elements (e.g., Click the **Save** button). +* **Rule:** Use *italics* for file names (e.g., Open the *config.yaml* file). + +#### **D. Punctuation and Capitalization** +This section covers the nitty-gritty details of punctuation and capitalization. +* **Rule:** Use the Oxford comma for lists (e.g., "Install Python, Node.js, and Git."). +* **Rule:** Capitalize product names consistently (e.g., "Codeharbor" vs. "CodeHarbor"). + +## How to Apply a Style Guide + +A style guide is useless if it's sitting unread on a shelf. Effective adoption relies on integration. + +1. **Use a Linter (Review from the previous tutorial):** As mentioned in the **Writing Tools** tutorial, integrate a tool like [Vale](https://docs.errata.ai/) into your Git workflow. This automatically flags violations of your style guide rules *before* the content is published. +2. **Define and Maintain a Glossary:** Keep a running, shared list of approved terms. If a new product name is launched, ensure it's immediately added to the glossary and communicated. +3. **Perform Style Reviews:** During the Pull Request (PR) process, treat style and clarity issues with the same importance as technical accuracy. Style reviews ensure standards are consistently upheld across the team. + +:::warning Guarding Against Scope Creep +A Style Guide is *not* a process manual. Avoid including rules about workflow (e.g., "how to name files") in your style guide. Stick to rules about language, presentation, and content consistency. +::: + +--- + +You now understand the importance of style guides in professional technical communication. + +By adhering to a well-defined style guide, you ensure that your documentation is not only clear and consistent but also reflects the professionalism of your organization. \ No newline at end of file diff --git a/docs/technical-writer/tools/version-control-github.mdx b/docs/technical-writer/tools/version-control-github.mdx index e345ed2..543536a 100644 --- a/docs/technical-writer/tools/version-control-github.mdx +++ b/docs/technical-writer/tools/version-control-github.mdx @@ -1 +1,98 @@ - \ No newline at end of file +--- +title: Version Control for Docs +sidebar_label: "3. Version Control GitHub" +description: "Master the core concepts of Git, the industry standard for version control, and use GitHub to collaborate on and manage documentation alongside source code." +--- + +**Git** is the distributed version control system (VCS) used by virtually every modern software team. **GitHub** (or GitLab, Bitbucket) is the cloud service that hosts Git repositories and provides a web interface for collaboration. + +For a technical writer practicing **Docs-as-Code**, Git is the tool that tracks every sentence, comma, and code block change, ensuring your documentation remains safe, auditable, and collaborative. + +## Core Concept: Commits and History + +Git's main job is to take "snapshots" of your project files (including your Markdown docs) over time. + +* A **Commit** is a single snapshot that records all the changes you made since the last snapshot. Every commit must have a descriptive message (e.g., "DOCS: Fixed broken link in installation guide"). +* The **History** is the sequence of all commits, forming a linear record of your project's evolution. If something breaks, you can always revert the entire project to a past, working commit. + +## The Central Workflow: Branches, Pull Requests, and Merges + +When working on docs, you should never edit the main, live version (usually called `main` or `master`). Instead, you follow a standardized process to manage changes safely. + +### 1. **Clone the Repository** + +You start by downloading a copy of the central project files (the repository) from GitHub to your local machine. This is called **cloning**. + +```bash title="Downloads the repository from the cloud to your computer" +git clone [repository-url] +``` + +### 2. **Create a Branch** + +```bash title="Creates a new branch for your changes" +git checkout -b [branch-name] +``` + +A **Branch** is a safe, parallel line of development. Any changes you make in your branch won't affect the live documentation until you explicitly approve them. + +```bash title="Creates a new branch named 'fix-bug-in-api-doc' and switches to it" +git checkout -b fix-bug-in-api-doc +``` + +### 3. **Commit Your Changes (The Snapshot)** + +```bash title="Commits your changes" +git commit -m "DOCS: Fixed broken link in installation guide" +``` +After writing your content, you need to stage the files and commit them. + +1. **Stage Files:** Tell Git which files you want to include in your commit. + + ```bash title="Stages all changed files in the current directory" + git add . + ``` + +2. **Commit:** Create the snapshot with a descriptive message. + + ```bash title="Creates the commit" + git commit -m "DOCS: Clarified input parameters for POST endpoint /users." + ``` + +### 4. **Push to GitHub** + +You upload your local branch and its new commits to the remote GitHub repository. + +```bash title="Pushes the branch (and its changes) to GitHub" +git push origin fix-bug-in-api-doc +``` + +### 5. **Create a Pull Request (PR)** + +```bash title="Creates a pull request" +gh pr create --base main --head fix-bug-in-api-doc --title "Fix broken link in installation guide" --body "This PR fixes a broken link in the installation guide." +``` +The **Pull Request** is the heart of collaboration. + + * Once your changes are on GitHub, you open a PR asking for your new branch (`fix-bug-in-api-doc`) to be merged into the main line of documentation (`main`). + * The PR is the place where other writers, engineers, or product managers **review** your changes, suggest edits, and approve the content. + +### 6. **Merge and Deploy** + +Once the PR is approved, a lead writer or engineer **merges** your branch into `main`. This is the point where your documentation changes become part of the central, live codebase. + +Often, merging the PR triggers an automated process (like a **Continuous Integration/Continuous Deployment, or CI/CD, pipeline**) that automatically rebuilds and publishes the documentation website. + +## Best Practices for Technical Writer Commits + +Because your commits are part of the permanent record, clarity is paramount. + +| Goal | Best Practice | Example | +| :--- | :--- | :--- | +| **Clarity** | Use a clear prefix to identify the change type. | `DOCS:`, `FEAT:`, `FIX:`, `CHORE:` | +| **Conciseness** | Keep the subject line short (under 50 characters). | `FIX: Corrected error in setup script parameters` | +| **Specificity** | Reference the location or ticket number. | `DOCS: Updated requirements for feature X (JIRA-203)` | +| **Tense** | Use the **imperative mood** (it tells what the commit *does*). | **Good:** `Update` the title. **Bad:** `Updated` the title. | + +> **A good commit message should answer the question:** "If this commit is applied, it will..." + +Mastering the Git workflow is the single most valuable tool a modern technical writer can possess, as it fully integrates you into the product development lifecycle. \ No newline at end of file diff --git a/docs/technical-writer/tools/writing-tools.mdx b/docs/technical-writer/tools/writing-tools.mdx index e345ed2..138f6ec 100644 --- a/docs/technical-writer/tools/writing-tools.mdx +++ b/docs/technical-writer/tools/writing-tools.mdx @@ -1 +1,65 @@ - \ No newline at end of file +--- +title: Content Enhancement Tools +sidebar_label: "4. Writing Tools" +description: "A technical writer's essential toolkit for ensuring consistency, clarity, grammar, and adherence to style guides before publishing documentation." +--- + +Once you've structured your document in Markdown and committed it via Git, your work isn't quite done. You need a final layer of polish. This is where specialized writing tools come in, helping you enforce style, check clarity, and stamp out grammatical errors. + +The best tools for technical writers automate the tedious checks so you can focus on complex concepts. + +## 1. Grammar and Spell Checkers + +These tools are the baseline for professional communication. They catch the obvious mistakes that even seasoned writers miss during a fast review. + +| Tool | Focus | Key Feature for Tech Writers | +| :--- | :--- | :--- | +| **Grammarly** | General grammar, tone, and clarity. | **Browser extension** that works across almost all web interfaces (GitHub, Hosted CMS, etc.). | +| **Microsoft Editor** | Grammar, spelling, and style suggestions within the Microsoft Office suite. | Deep integration with Word/Outlook for writers who frequently draft non-Markdown content. | +| **ProWritingAid** | In-depth analysis of style, readability, and repetitive wording. | Offers detailed **readability scores** (like Flesch-Kincaid), great for optimizing user comprehension. | + +:::tip Clarity is King +In technical writing, correctness is more important than flair. While these tools might suggest a synonym for a technical term, **always prioritize consistency** over variety. If the API calls it a "Widget ID," don't let Grammarly change it to a "Gizmo Identifier." +::: + +## 2. Style Guide Enforcement (Linting) + +This is the next level of professionalism. Linting tools check your content against a codified set of rules, ensuring you use consistent terminology, heading case, and punctuation across your entire documentation set. + +The goal is to maintain a unified voice and style, making the content feel like it was written by one entity, not twenty different people. + +### Vale (The Technical Writer’s Linter) + +Vale is the most popular open-source tool for documentation linting. + +* **How it Works:** Vale runs checks based on custom style guides (like the Microsoft Writing Style Guide, Google Developer Documentation Style Guide, or your company's own custom rules). +* **What it Checks:** + * **Terms:** Flagging non-approved terms (e.g., catching "login" instead of the approved "log in"). + * **Tone:** Identifying passive voice, informal language, or slang. + * **Formatting:** Enforcing rules like capitalization of headings or avoiding double spaces. +* **Integration:** It integrates perfectly with your development workflow, often running automatically as part of the **CI/CD pipeline** when you create a Pull Request on GitHub. If your doc breaks a style rule, the build fails. + +## 3. Readability Checkers + +A separate function often built into the tools above (like ProWritingAid), readability checkers use algorithms to assess how easy your content is to understand. + +| Metric | What it Measures | Why it Matters | +| :--- | :--- | :--- | +| **Flesch-Kincaid** | Measures grade level based on sentence length and word difficulty. | Most technical docs aim for a Grade 8–10 level to ensure global accessibility. | +| **Passive Voice Score** | Measures how often sentences use the passive voice ("the error was found"). | Active voice ("you will find the error") is clearer and more direct, which is vital in instructions. | +| **Long Sentences** | Counts sentences over a specific length (e.g., 20 words). | Long sentences introduce complexity and can obscure instructions. | + +:::tip +When you write procedural steps, always try to keep your average sentence length under **15 words**. Your users are performing an action, and they need immediate clarity. +::: + +## 4. Link Checkers + +Nothing screams unprofessionalism like a broken link. As documentation platforms are updated and file names change, old links often become invalid. + +* **Tools:** Most Static Site Generators (Docusaurus, MkDocs) have **built-in link checkers** that run during the build process. +* **Function:** They crawl the site's generated pages and verify that every internal link (`../setup.mdx`) and external link (`https://example.com`) returns a valid status (HTTP 200). + +--- + +By integrating a linter (like Vale) and a strong grammar checker (like Grammarly) into your workflow, you create a robust safety net that elevates the quality and consistency of your technical content. \ No newline at end of file diff --git a/docs/terraform/index.mdx b/docs/terraform/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/terraform/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/typescript/index.mdx b/docs/typescript/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/typescript/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/vue/index.mdx b/docs/vue/index.mdx new file mode 100644 index 0000000..e345ed2 --- /dev/null +++ b/docs/vue/index.mdx @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/src/components/LinkCard.tsx b/src/components/LinkCard.tsx new file mode 100644 index 0000000..abfb2ba --- /dev/null +++ b/src/components/LinkCard.tsx @@ -0,0 +1,72 @@ +import Link from '@docusaurus/Link'; +import { FaBook, FaCodeBranch, FaExternalLinkAlt, FaTerminal } from 'react-icons/fa'; + +const getIconComponent = (iconName: string) => { + switch (iconName.toLowerCase()) { + case 'git': + // Using a branch icon to represent the Git workflow + return ; + case 'book': + return ; + case 'terminal': + return ; + default: + // Default icon if none is matched + return ; + } +}; + +/** + * A visually styled card component for external or internal links. + * * @param {object} props + * @param {string} props.title - The title of the card. + * @param {string} props.description - The descriptive text of the card. + * @param {string} props.link - The URL to link to. + * @param {string} [props.icon] - The name of an icon to display (e.g., 'git', 'book'). + */ +const LinkCard = ({ title, description, link, icon }: { title: string; description: string; link: string; icon?: string; }) => { + const IconComponent = getIconComponent(icon || 'default'); + + return ( + +
+ {/* Icon Area */} +
+ {IconComponent} +
+ + {/* Content Area */} +
+

+ {title} + +

+

+ {description} +

+
+
+ + ); +}; + +export default LinkCard; \ No newline at end of file