diff --git a/docs/technical-writer/documentation/api-documentation.mdx b/docs/technical-writer/documentation/api-documentation.mdx index e345ed2..ff4fddd 100644 --- a/docs/technical-writer/documentation/api-documentation.mdx +++ b/docs/technical-writer/documentation/api-documentation.mdx @@ -1 +1,99 @@ - \ No newline at end of file +--- +title: "API Documentation" +sidebar_label: "1. API Documentation" +description: "Master the essential structure of API documentation—Conceptual, Reference, and Tutorials—to enable quick and effective developer integration." +image: /tutorial/img/tutorials/technical-writer/api-documentation-cover.png +--- + +import SkillCard from '@site/src/components/SkillCard'; +import { FaBookOpen, FaLaptopCode, FaWrench, FaCogs } from 'react-icons/fa'; + +For developers, an **API (Application Programming Interface) is the product, and the documentation is the user experience.** Your goal is to make the API so easy to use that the developer spends less time reading your words and more time writing their code. + +:::warning Think of it this way +The API is the engine, and your documentation is the owner's manual. If the manual is missing pages or is unclear, the engine is useless. +::: + +--- + +## The Three Pillars of API Documentation + +Good API documentation is organized into three distinct, yet interconnected, sections. This structure ensures users can find the information they need based on their current goal (understanding, building, or looking up a detail). + +
+ } + /> + } + /> + } + /> +
+ +### Detailed Content Breakdown + +| Section | Target Audience | Key Content to Include | +| :--- | :--- | :--- | +| **Conceptual** | New users, decision-makers, architects | Overview, Use Cases, Core Concepts, Authentication/Authorization, Rate Limits. | +| **Tutorials** | Developers integrating for the first time | Quickstart Guide, Step-by-step for key workflows, Error handling examples. | +| **Reference** | Developers actively coding and debugging | Detailed list of **Endpoints**, HTTP Methods (`GET`, `POST`, `PUT`), **Parameters** (query, path, body), **Request/Response bodies** (schemas), **Status Codes**. | + +--- + +## Best Practices for Reference Documentation + +The Reference section is often the most challenging to write, but thanks to specifications like **OpenAPI (Swagger)**, much of it can be *auto-generated* from the code itself. + +### 1. Endpoint Clarity + +Every endpoint must be documented with the following: + +* **URI:** The path (e.g., `/v1/users/{id}`). +* **Method:** The HTTP verb (`GET`, `POST`, `DELETE`). +* **Description:** A clear, concise sentence explaining what the endpoint does (e.g., "Retrieves the user object for a given ID."). + +### 2. Parameter Detail + +For every parameter (whether in the path, query string, or request body): + +| Field | Example | Must Include | +| :--- | :--- | :--- | +| **Name** | `id` | Required | +| **Location** | Path | Required | +| **Type** | `integer` | Required | +| **Description** | The unique ID of the user. | Required | +| **Example** | `12345` | Highly Recommended | + +### 3. Request and Response Bodies + +Show, don't tell. A JSON payload is worth a thousand words. + +* **Request Body:** Provide a complete example of the JSON or XML payload expected for `POST` or `PUT` requests. +* **Response Body:** Provide successful (`200 OK`, `201 Created`) and common error (`400 Bad Request`, `404 Not Found`) response examples. Always clearly document the schema (data structure). + +```json +// Example of a successful 200 GET /v1/users/12345 response +{ + "user_id": 12345, + "first_name": "Alex", + "last_name": "Damon", + "status": "active" +} +``` + +### 4. Interactive Documentation + +The gold standard for API docs is **interactivity**. Using tools like **Swagger UI** or **Postman**, developers should be able to: + + * **Try it Out:** Make a live API call directly from the documentation. + * **Code Samples:** See the request generated in multiple languages (cURL, Python, JavaScript) to copy-paste. + +If your tool chain supports auto-generation, **make the documentation a single source of truth** by pulling directly from the OpenAPI file. If the code changes, the documentation changes—or it fails to build! \ No newline at end of file diff --git a/docs/technical-writer/documentation/release-notes.mdx b/docs/technical-writer/documentation/release-notes.mdx index e345ed2..62c92c2 100644 --- a/docs/technical-writer/documentation/release-notes.mdx +++ b/docs/technical-writer/documentation/release-notes.mdx @@ -1 +1,82 @@ - \ No newline at end of file +--- +title: "Release Notes & Announcements" +sidebar_label: "5. Release Notes" +description: "Learn the concise structure and critical content selection process for writing effective Release Notes that delight users and manage expectations during product updates." +--- + +Release Notes (or Release Announcements) are brief, direct documents that accompany a new product release, patch, or update. They serve as the official record of what has changed, fixed, or been added. + +The challenge? They must appeal to both the excited early adopter and the frustrated user looking for a specific bug fix, all while being short enough to be read in under a minute. + +## Audience and Purpose + +The audience for Release Notes is the **active user base**. They want to know three things, in order: + +1. **Is this important to me?** (Determine if they need to update now.) +2. **What problem does it solve?** (Validate a frustration they had.) +3. **How do I use the new thing?** (The next step.) + +| Goal | Description | +| :--- | :--- | +| **Manage Expectations** | Inform users that known issues are addressed, or that a requested feature is now live. | +| **Reduce Support Load** | Announce known issues or workarounds, preventing a flood of tickets after an update. | +| **Provide a Legal Record** | Serve as a formal record of changes for regulatory compliance (common in finance/health sectors). | +| **Generate Excitement** | Highlight major new features to drive user engagement and adoption. | + +## The Essential Structure of Release Notes + +Unlike formal reports or comprehensive manuals, Release Notes are highly standardized and prioritized by impact. The structure is essentially a concise list categorized by type of change. + +### 1. Header and Summary + +* **Title:** Clear, high-level version designation (e.g., "Version 4.5.1 Released," or "May 2025 Security Patch"). +* **Release Date:** The date the changes went live. +* **A Brief Overview:** A one-paragraph summary of the **most significant changes**. If there's one major feature, lead with it. If it's all bug fixes, state that clearly. + +### 2. Categorized Changes (The Core) + +The content should be grouped using clear, bold headings. This allows users to quickly scan for what interests them. + +#### **A. New Features and Enhancements** + +* Focus on the **user benefit**, not the technical implementation. +* Use a one-sentence description, followed by a link to the detailed documentation (e.g., the User Manual). +* **Format Example:** + * **New:** **Dark Mode Theme.** You can now switch to Dark Mode in the User Settings menu for improved viewing comfort. [Link to documentation] + * **Enhanced:** **Faster Report Generation.** Large data reports now complete 40% faster due to backend optimization. + +#### **B. Fixed Bugs (The "Bug Smash")** + +* List the fixed issues clearly. If possible, use the exact wording or ticket ID the user might have reported or seen in a forum. +* Avoid overly technical descriptions unless the audience is highly technical (e.g., developer APIs). +* **Format Example:** + * Fixed an issue where filtering by date range would occasionally exclude the last day of the selection. + * Resolved **API Error 500** that occurred when attempting batch uploads with more than 100 items. + +#### **C. Known Issues and Deprecations** + +* This is crucial for setting expectations. Tell the user what you know is broken or what is going away. +* For known issues, provide a temporary **workaround** if one exists. +* For deprecations, clearly state *why* the item is being removed and *what* the new replacement is. + + + +## Best Practices for Writing Clear Release Notes + +### 1. Be Concise and Direct + +If you can say it in 5 words, don't use 25. Release Notes are a news flash, not a novel. Avoid marketing fluff in the detail sections. + +> **Bad:** "We have developed a groundbreaking, highly innovative new solution that completely changes the paradigm of saving." +> +> **Good:** "Improved Save Function: Saving large documents is now instantaneous." + +### 2. Prioritize the User’s Perspective + +* When describing a fix, don't just state the action, state the outcome for the user. + * **Good:** "Fixed: Clicking the 'Export' button no longer freezes the application." +* Use **present or past tense** consistently, depending on your company's style guide (e.g., "We fixed," "We have introduced," or "Fixes: ...," "Adds: ..."). + +### 3. Maintain Consistency (The Series Effect) + +Release notes are rarely standalone documents; they are a series. Maintain a consistent structure, tone, and set of headings across every release. Users should know exactly where to look for the "Bug Fixes" section every time. \ No newline at end of file diff --git a/docs/technical-writer/documentation/software-documentation.mdx b/docs/technical-writer/documentation/software-documentation.mdx index e345ed2..151ec88 100644 --- a/docs/technical-writer/documentation/software-documentation.mdx +++ b/docs/technical-writer/documentation/software-documentation.mdx @@ -1 +1,52 @@ - \ No newline at end of file +--- +title: "Software Documentation" +sidebar_label: "2. Software Documentation" +description: "Understand the essential types of software documentation, their audiences, and best practices for creating clear, effective internal and external content." +--- + +Software documentation is the map and manual for any application or system. It serves two primary masters: the **end-user** and the **developer**. As a technical writer, your job is to speak both languages fluently. Get it right, and the product is a success; get it wrong, and you're the reason for a very confusing support ticket avalanche. + +--- + +## The Two Pillars: Internal vs. External Docs + +All software documentation falls into one of two major categories, defined by its audience. + +### 1. External (User-Facing) Documentation + +This content is for your **customers**—the people who actually use the software. Its goal is to guide them to success and reduce support costs. + +| Document Type | Audience | Purpose | Example | +| :--- | :--- | :--- | :--- | +| **User Guides / Manuals** | End-users (varying skill levels) | A comprehensive, task-oriented guide on how to use the product's features. | "How to set up your account profile," "Creating your first project." | +| **Tutorials / Walkthroughs** | New users | Sequential learning steps to help a user achieve a specific, meaningful outcome. | "A 5-minute guide to publishing your first blog post." | +| **Knowledge Base / FAQs** | All users | Self-service articles to answer common questions and troubleshoot minor issues. | "What to do if your payment fails," "Changing your API key." | +| **Release Notes / Changelogs** | All users | A concise list of new features, enhancements, and bug fixes in a new version. | "Version 2.3.0 is here: New Dashboard Analytics and UI fixes." | + +### 2. Internal (Developer-Facing) Documentation + +This content is for the **development team** and other technical stakeholders. Its goal is to document the system's architecture, design, and code for maintenance and future development. + +| Document Type | Audience | Purpose | Example | +| :--- | :--- | :--- | :--- | +| **API Documentation** | Developers, Integrators | Detailed reference for every function, class, method, and parameter in an Application Programming Interface. | The complete list of GET/POST/PUT endpoints and expected responses. | +| **System/Architecture Docs** | Developers, Engineers | High-level overview of the system's structure, components, and data flow. | A diagram showing how the frontend, backend, and database interact. | +| **Code Documentation** | Developers (internal) | Comments and docstrings within the source code explaining why the code does what it does. | Javadoc or Python docstrings explaining a complex function. | +| **Requirements Documents** | Project Managers, Developers | Documents detailing the functional and non-functional requirements for the software. | A Product Requirements Document (PRD) defining the feature's scope. | + +--- + +## Essential Writing Best Practices + +Regardless of the audience, great software documentation shares a few key traits. Follow these, and you'll be ahead of the curve: + +* **Know Your Audience (and Their Acronyms):** You wouldn't write a "How to Install the SDK" guide using marketing copy. Use technical terminology for developers, and plain language for end-users. Always create a **Glossary** if your documentation uses specific jargon. +* **Emphasize Task-Orientation:** Users come to documentation with a goal. Structure your content around **tasks** and **outcomes** (e.g., "Set up two-factor authentication") rather than just product features. +* **Consistency is Your Superpower:** Maintain a consistent **style, tone, and formatting** across all documents. A **Style Guide** is non-negotiable for this. Use consistent headings, bullet points, and code block styles. +* **Visuals Aren't Optional:** Screenshots, diagrams, and short video clips break up text and instantly clarify complex steps. A picture is worth a thousand words, and in documentation, it's worth a thousand frustrated clicks. +* **Treat Docs Like Code (Docs-as-Code):** Use version control (like Git) for your documentation. This ensures your docs are reviewed, tested, and released alongside the code, keeping them **up-to-date** the single biggest challenge in documentation. + +:::tip The Technical Writer's Wit +Your goal isn't to make the product look good; it's to make the user **feel** good about using it. If they find what they need in two clicks, you're a hero. If they call support, well, you've just created a job for someone else. +::: + diff --git a/docs/technical-writer/documentation/technical-reports.mdx b/docs/technical-writer/documentation/technical-reports.mdx index e345ed2..699d492 100644 --- a/docs/technical-writer/documentation/technical-reports.mdx +++ b/docs/technical-writer/documentation/technical-reports.mdx @@ -1 +1,71 @@ - \ No newline at end of file +--- +title: "Technical Reports" +sidebar_label: "4. Technical Reports" +description: "Master the formal structure, audience, and content required to produce professional, analytical Technical Reports for internal stakeholders and subject matter experts." +--- + +Technical Reports are formal, factual, and analytical documents. Unlike a user manual, which focuses on **task completion**, a report focuses on **investigation, analysis, and recommendation**. You are not instructing; you are informing decision-makers. + +## Audience: The Decision-Makers and Experts + +Your primary audience is generally **internal**, highly educated, and focused on outcomes. They might be executives, project managers, or fellow Subject Matter Experts (SMEs). + +| Audience Type | Their Focus | Your Writing Style | +| :--- | :--- | :--- | +| **Executives/Managers** | **Decision-Making** (Budget, timeline, resource allocation). | They only read the **Executive Summary** and **Conclusion/Recommendations**. Keep these sections clear, concise, and focused on business impact. | +| **SMEs/Engineers** | **Methodology** and **Data** (The technical validity of your findings). | They dive into the **Body** and **Appendices**. Use precise terminology, present data objectively, and cite your sources rigorously. | + +## The Standard Formal Report Structure + +Technical reports follow a highly standardized structure. Each part serves a specific purpose for different readers, maximizing scannability and credibility. + +### I. Front Matter (The Quick Hits) + +This content allows the high-level audience to grasp the report's essence quickly. + +* **Title Page:** Includes the title, author(s), date, and organization. +* **Letter of Transmittal (Optional):** A brief cover memo stating who authorized the report and what it is about. +* **Table of Contents:** Crucial for navigation. Use a hierarchical numbering system (1.0, 1.1, 1.1.1). +* **Abstract (or Summary):** A single, brief paragraph (typically under 250 words) covering the objective, method, key results, and conclusion. **Write this last!** +* **Executive Summary:** A longer, one-page condensation for busy executives. It provides context and highlights recommendations without requiring the reader to touch the main body. + +### II. Body (The Technical Core) + +This is where you earn your technical stripes. Every claim must be substantiated. + +1. **Introduction (Section 1.0):** + * **Problem Statement:** What question are you trying to answer? (e.g., "Determine the feasibility of migrating the platform to Serverless architecture.") + * **Scope:** What are the boundaries of your investigation? What is *not* covered? + * **Objectives:** What specific goals did you set out to achieve? + * **Background/Literature Review (if applicable):** Contextualize your work within existing knowledge or previous projects. + +2. **Methodology/Procedure (Section 2.0):** + * Describe the process, steps, tools, and materials used in your study, experiment, or investigation. + * It must be detailed enough for a peer to **replicate your work**. + +3. **Results (Section 3.0):** + * **Present the data objectively.** Use clear, well-labeled tables, charts, and figures. + * Avoid interpretation here. This section is purely **what you found**. + +4. **Discussion (Section 4.0):** + * **Interpret the data.** What do the results mean? + * Discuss the significance, potential implications, and comparison to previous findings or hypotheses. + * Acknowledge any **study limitations or sources of error**. + +5. **Conclusion (Section 5.0):** + * Summarize the main outcomes and relate them directly back to the problem statement/objectives in your Introduction. + * ***Do not introduce new information.*** + +### III. Back Matter (The Proof) + +This section provides the evidence and sources necessary for technical validation. + +* **Recommendations:** The most action-oriented part. Based on your Conclusion, what specific actions should the company take? (e.g., "Allocate \$50,000 to phase one pilot project," or "Delay implementation until X factor is addressed.") +* **References/Bibliography:** A formal list of all sources cited in a consistent academic style (APA, IEEE, etc.). +* **Appendices:** Raw data, large-scale diagrams, meeting minutes, calculation sheets, long code snippets—anything that supports the report but would clutter the main text. + +## Key Report Writing Principles + +* **Be Objective:** Use the passive voice judiciously, but always maintain an impersonal, objective tone. (e.g., "The data suggests..." not "I think the data suggests...") +* **Structure over Style:** Clarity of structure is paramount. Use clear, informative headings and a consistent numbering system (e.g., **4.2.1 Component Failure Rate**). +* **The Power of Graphics:** Every figure and table must be numbered, captioned, and **referred to in the text** (e.g., "As demonstrated in **Figure 3.1**, the performance degraded exponentially..."). If you don't mention it, don't include it. \ No newline at end of file diff --git a/docs/technical-writer/documentation/user-manuals.mdx b/docs/technical-writer/documentation/user-manuals.mdx index e345ed2..4213fc9 100644 --- a/docs/technical-writer/documentation/user-manuals.mdx +++ b/docs/technical-writer/documentation/user-manuals.mdx @@ -1 +1,67 @@ - \ No newline at end of file +--- +title: "User Manuals and Guides" +sidebar_label: "3. User Manuals" +description: 'Learn the structure, audience considerations, and best practices for creating effective, task-oriented User Manuals that empower your customers.' +--- + +The user manual is the primary document your customer turns to when they need to accomplish a task. Its existence significantly cuts down on support tickets. Your mission is simple: get the user from "I have a problem" to "I solved it" as quickly and painlessly as possible. + +## Audience: The User, Not the Engineer + +Unlike internal documentation, the user manual is written for a non-technical or semi-technical audience. + +**Key Audience Considerations:** + +1. **They are Goal-Oriented:** Users don't read manuals for fun. They come with a specific task (e.g., "I need to print this document," or "How do I add a new team member?"). Your content must prioritize solving that problem immediately. +2. **They Hate Jargon:** Avoid developer-speak, obscure acronyms, and internal project names. If you must use a technical term, define it in a simple **Glossary**. +3. **They Skim:** Assume the user will only read the bare minimum. Use strong headings, bold key terms, and visual aids to make the content easy to scan. + +## The Structure of a Great User Manual + +Effective user manuals are not encyclopedias; they are organized for navigation and task completion. A common, highly effective structure is the **DITA model** of **Concept, Task, and Reference**. + +### 1. Concepts (Understanding the "Why") +This section provides a foundational understanding of a feature or a larger system. It introduces the user to the underlying idea before the "how-to." + +* **Content Focus:** Explanations, overviews, and terminology. +* **Example Headings:** "Understanding the Dashboard," "What is a Project in this Software?", "Key Terminology." + +### 2. Tasks (The Core "How-To") +This is the heart of the user manual. Each topic in this section must be a clear, step-by-step procedure designed to help the user complete a single, definable action. + +* **Content Focus:** Sequential, numbered steps, clear instructions, and expected outcomes. +* **Best Practice:** Each task should start with a clear objective (e.g., "To create a new report, follow these steps...") and use **action verbs** (Click, Select, Enter, Navigate). + +**A well-structured task is a life-saver:** +1. **Navigate** to the **Settings** menu. +2. In the **User Preferences** section, **click** the **Edit Profile** button. +3. **Enter** your new email address in the field labeled **Primary Email**. +4. **Click** **Save Changes**. A confirmation message will appear. + +### 3. Reference (Looking Up the "What") +This content is for quick lookup and technical details. It is not sequential reading; it's a resource to be consulted. + +* **Content Focus:** Tables, lists, field descriptions, API details (if public-facing), and error messages. +* **Example Headings:** "Error Codes and Troubleshooting," "Field Definitions," "System Requirements." + +## Best Practices for Writing Clear User Guides + +### **Keep it Scannable with Formatting** + +* **Use Lists:** Always use **numbered lists** for steps (sequence matters) and **bulleted lists** for features, options, or prerequisites (sequence does not matter). +* **Use Visuals Strategically:** After a block of 3-5 steps, include a **screenshot** or **diagram** to confirm the user is on the right track. +* **Consistent Highlighting:** Use a consistent method (e.g., **bolding**) for all interface elements (buttons, menus, links) to help the reader visually parse instructions. + +### **The "In-App Text" Trap** + +A common mistake is treating your manual like a separate book. Your documentation must align perfectly with the software's UI text. + +* If the button in the app says "Submit Order," your documentation must say: "Click the **Submit Order** button." +* If the error message is "Authentication Failed," your troubleshooting guide must address the error using that exact phrase. + +### **Focus on Troubleshooting** + +The moment a user encounters an error, their patience drops to zero. A great user manual anticipates failure: + +* **In-line Troubleshooting:** For complex tasks, add a note like: "If you receive the 'Timeout' error, check your firewall settings before continuing." +* **Dedicated Section:** Create a dedicated **Troubleshooting/FAQ** section that addresses common pain points and known limitations. \ No newline at end of file diff --git a/docs/technical-writer/fundamentals/document-structure-and-formatting.mdx b/docs/technical-writer/fundamentals/document-structure-and-formatting.mdx index b51d156..4a27baf 100644 --- a/docs/technical-writer/fundamentals/document-structure-and-formatting.mdx +++ b/docs/technical-writer/fundamentals/document-structure-and-formatting.mdx @@ -6,6 +6,11 @@ image: /tutorial/img/tutorials/technical-writer/structure-and-formatting-cover.p --- import { FaBook, FaWrench, FaCode, FaLightbulb } from 'react-icons/fa'; +import thumbnail from '/img/tutorials/technical-writer/structure-and-formatting-cover.png'; + + + +
Writing well is only half the battle. If your users can't find the information they need, or if the content they find mixes learning materials with quick facts, your documentation fails. diff --git a/docs/technical-writer/fundamentals/review-and-editing.mdx b/docs/technical-writer/fundamentals/review-and-editing.mdx index e345ed2..80869c6 100644 --- a/docs/technical-writer/fundamentals/review-and-editing.mdx +++ b/docs/technical-writer/fundamentals/review-and-editing.mdx @@ -1 +1,93 @@ - \ No newline at end of file +--- +title: "Review and Editing" +sidebar_label: "5. Review and Editing" +description: "Implement a rigorous review cycle, focusing on technical accuracy, clarity, and consistency before publishing any documentation." +image: /tutorial/img/tutorials/technical-writer/review-editing-cover.png +--- + +import thumbnail from '/img/tutorials/technical-writer/review-editing-cover.png'; + + + +
+ +The best technical writers treat the review process as the most important phase of the writing cycle. Documentation that is technically incorrect or riddled with errors erodes user trust instantly. + +The review process has two distinct stages: **Self-Editing** (you check the words) and **Peer Review** (others check the facts). + +--- + +## Stage 1: The Self-Editing Checklist + +Before you hand your work to an engineer or a manager, you must run a final check on your own work. Think of this as your final build step before deployment. + +### 1. Technical Accuracy Check (The "Can I Copy-Paste This?" Rule) + +This is paramount for developer documentation. + +* **Execute Every Step:** Go through your instructions *as if you were the user*, following only the text you wrote. Do all commands work? Do all links resolve? +* **Verify Code Snippets:** Copy-paste every single code block and command line argument into a terminal. Do they run without errors? Do they produce the expected output? +* **Check Screenshots:** Do your visual aids still accurately reflect the UI? (UIs change faster than code). + +### 2. Style and Tone Check (The "Plain English" Rule) + +Review your draft using the principles we discussed in the **Writing Style and Tone** section. + +* **Active Voice:** Search for forms of "to be" (`is`, `was`, `will be`). Can you rewrite the sentence in the active voice? +* **Conciseness:** Delete all filler phrases: "in order to," "it should be noted that," "as you can see." +* **Terminology:** Check your document against your team's style guide or glossary. Are you using the correct capitalization for product names and acronyms (e.g., is it `GitHub` or `Github`)? + +### 3. Formatting and Structure Check + +* **Hierarchy:** Do you have a consistent use of H1, H2, and H3 headings? +* **Lists:** Are all sequential steps written as **numbered lists**? Are all non-sequential items in bullet lists? +* **Cross-References:** Do all internal links and cross-references (e.g., "See the **API Reference** for details...") point to the correct location? + +--- + +## Stage 2: Peer and Technical Review + +After you've done your due diligence, you need external eyes. You need two main types of reviewers: + +### 1. The Subject Matter Expert (SME) Review + +**Goal: 100% Technical Accuracy.** + +* **Who:** The engineer, developer, or product manager who built the feature you are documenting. +* **Focus:** The SME doesn't need to check your grammar; they need to confirm that your steps, code, prerequisites, and explanations are *factually correct*. +* **How:** Use a Git-based workflow (like a Pull Request in GitHub/GitLab) so the SME can easily comment directly on the lines of code or steps that are wrong. + +### 2. The Fresh Eyes Review + +**Goal: Clarity and Usability.** + +* **Who:** Another technical writer, an editor, or a tester who is *unfamiliar* with the feature. +* **Focus:** This person acts as a proxy for your user. They should be able to follow the documentation **without any prior knowledge**. +* **Key Question:** If they get stuck, your documentation is the problem, not their skill level. + +:::note Wit Check +If your reviewer has to ask, "Wait, what does that acronym mean?" or "Where do I find that button?", your document failed the clarity test. Fix it. +::: + +:::warning Choosing the Right Reviewer +Avoid asking the SME to do the Fresh Eyes review. They are too close to the material and will unconsciously fill in gaps that a new user would struggle with. +::: + +:::tip Clarity Tips for Fresh Eyes Reviewers +Provide your reviewer with a checklist to guide their review: +* **Follow the Steps:** Can they complete the task by following only your documentation? +* **Highlight Confusing Parts:** Ask them to mark any sections that were unclear or ambiguous. +* **Suggest Improvements:** Encourage them to propose clearer wording or additional explanations where needed. +::: + +### Iterative Process: Review is a Loop + +Reviewing is not a single step; it’s a cycle. The ideal flow looks like this: + +1. **Draft Complete** +2. **Self-Edit & Test** (Fix 80% of errors) +3. **SME Review** (Fix technical errors) +4. **Fresh Eyes Review** (Fix clarity errors) +5. **Final Polish and Publish** + +After each review, revise your document and, if necessary, send it back for another round of review until all parties are satisfied. \ No newline at end of file diff --git a/docs/technical-writer/fundamentals/understanding-your-audience.mdx b/docs/technical-writer/fundamentals/understanding-your-audience.mdx index 075e261..cfd8243 100644 --- a/docs/technical-writer/fundamentals/understanding-your-audience.mdx +++ b/docs/technical-writer/fundamentals/understanding-your-audience.mdx @@ -5,7 +5,6 @@ description: "Learn the fundamental process of audience analysis, identify the f image: /tutorial/img/tutorials/technical-writer/audience-cover.png --- -import SkillCard from '@site/src/components/SkillCard'; import AudiencePersona from '@site/src/components/AudiencePersona'; import thumbnail from '/img/tutorials/technical-writer/audience-cover.png'; diff --git a/docs/technical-writer/fundamentals/visual-aids-and-graphics.mdx b/docs/technical-writer/fundamentals/visual-aids-and-graphics.mdx index e345ed2..9319179 100644 --- a/docs/technical-writer/fundamentals/visual-aids-and-graphics.mdx +++ b/docs/technical-writer/fundamentals/visual-aids-and-graphics.mdx @@ -1 +1,83 @@ - \ No newline at end of file +--- +title: "Visual Aids and Graphics" +sidebar_label: "4. Visual Aids and Graphics" +description: "Learn the best practices for using screenshots, diagrams, and videos to enhance comprehension, reduce reading time, and improve the user experience." +image: /tutorial/img/tutorials/technical-writer/visual-aids-cover.png +--- + +import { FaCamera, FaRulerCombined, FaArrowsAltH, FaVideo } from 'react-icons/fa'; +import thumbnail from '/img/tutorials/technical-writer/visual-aids-cover.png'; + + + +
+ +In technical documentation, **visual aids are not optional extras; they are part of the core content.** + +When a reader encounters a complex step, a well-placed screenshot or diagram can confirm their progress, clarify ambiguous text, and reduce cognitive load. This is especially true for UI-heavy applications and complex system architectures. + +--- + +## The Three Rules of Technical Graphics + +Before adding any image, ask yourself: *Does this visual aid make the next step easier to understand?* If the answer is no, the image is distracting. + +
+ } + /> + } + /> + } + /> +
+ +### Accessibility and Text Alternatives + +Remember that images are invisible to screen readers and search engines. You **must** provide descriptive text for every image. + +* **Alt Text (Required):** A concise, descriptive sentence that conveys the purpose of the image. (e.g., `alt="Screenshot of the Settings menu with the 'Advanced' tab selected."`) +* **Captions (Recommended):** Use captions for complex diagrams or figures that need a brief explanation directly beneath them. + +:::warning Don't Forget Dark Mode +If your documentation supports a dark theme (like this site), ensure your screenshots are either theme-agnostic (using a neutral background color) or include separate versions optimized for light and dark modes to prevent a jarring visual experience. +::: + +--- + +## When to Use Specific Visual Types + +The type of visual you choose should align with the content structure (which we learned about in the previous section). + +| Visual Type | Best Used In | Purpose | Tooling Examples | +| :--- | :--- | :--- | :--- | +| **Screenshot** | How-To Guides, Tutorials | To show the *result* of a step or the *next target* in a UI. | Snagit, ShareX, native OS tools. | +| **Flowchart/Diagram** | Explanations, Tutorials | To illustrate system architecture, data flow, or a decision tree. | Mermaid.js, PlantUML, Miro, Lucidchart. | +| **Code Snippets** | Reference, How-To Guides | While not a traditional "graphic," well-formatted code is a visual aid. | Code blocks with syntax highlighting. | +| **GIF / Short Video** | How-To Guides, Tutorials | For complex sequences of steps (e.g., drag-and-drop actions, filling out a form). | Loom, ScreenToGif. | + +### Diagramming with Code + +For technical documentation, relying on image files for diagrams has a major drawback: they are hard to update. + +A modern, developer-centric alternative is using a diagramming language like **Mermaid.js** (which Docusaurus can easily support via a plugin). This allows you to define a flowchart or sequence diagram using simple markup, which then renders into a scalable, theme-aware SVG. + +```mermaid +graph TD + A[User Starts Configuration] --> B{Choose Integration?}; + B -- Yes --> C[Select Slack]; + B -- No --> D[Continue Setup]; + C --> E[Verify Webhook URL]; + D --> F[Finalize]; + E --> F; +``` + +This approach treats your diagrams like code: they are versionable, easy to review, and maintain consistency automatically. \ No newline at end of file diff --git a/static/img/tutorials/technical-writer/review-editing-cover.png b/static/img/tutorials/technical-writer/review-editing-cover.png new file mode 100644 index 0000000..77a03c7 Binary files /dev/null and b/static/img/tutorials/technical-writer/review-editing-cover.png differ diff --git a/static/img/tutorials/technical-writer/structure-and-formatting-cover.png b/static/img/tutorials/technical-writer/structure-and-formatting-cover.png new file mode 100644 index 0000000..a6265cb Binary files /dev/null and b/static/img/tutorials/technical-writer/structure-and-formatting-cover.png differ diff --git a/static/img/tutorials/technical-writer/visual-aids-cover.png b/static/img/tutorials/technical-writer/visual-aids-cover.png new file mode 100644 index 0000000..0f2569d Binary files /dev/null and b/static/img/tutorials/technical-writer/visual-aids-cover.png differ