[{"data":1,"prerenderedAt":584},["ShallowReactive",2],{"guide-writing-technical-docs-markdown":3},{"id":4,"title":5,"body":6,"date":576,"description":577,"extension":578,"meta":579,"navigation":245,"path":580,"readingTime":382,"seo":581,"stem":582,"__hash__":583},"guides\u002Fguides\u002Fwriting-technical-docs-markdown.md","Writing Technical Documentation in Markdown",{"type":7,"value":8,"toc":569},"minimark",[9,18,23,39,44,90,108,112,115,160,183,186,190,193,223,253,262,266,269,341,344,386,389,393,396,509,514,557,565],[10,11,12,13,17],"p",{},"Markdown has become the default format for technical documentation. README files, API docs, design specs, and knowledge bases all use it. But good documentation is more than just ",[14,15,16],"code",{},".md"," files with some headings — it requires deliberate structure, consistent formatting, and a workflow that keeps content accurate over time.",[19,20,22],"h2",{"id":21},"structuring-technical-documents","Structuring Technical Documents",[10,24,25,26,30,31,34,35,38],{},"A technical document should answer three questions in order: ",[27,28,29],"strong",{},"what"," it is, ",[27,32,33],{},"how"," to use it, and ",[27,36,37],{},"why"," it works that way. Structure your Markdown accordingly.",[10,40,41],{},[27,42,43],{},"Recommended section order:",[45,46,47,54,60,66,72,78,84],"ol",{},[48,49,50,53],"li",{},[27,51,52],{},"Title and one-sentence summary"," — the frontmatter title plus a brief description in the first paragraph",[48,55,56,59],{},[27,57,58],{},"Prerequisites"," — what the reader needs before starting (installed tools, API keys, knowledge)",[48,61,62,65],{},[27,63,64],{},"Quick start"," — the shortest path to a working result",[48,67,68,71],{},[27,69,70],{},"Detailed explanation"," — expand on each concept with examples",[48,73,74,77],{},[27,75,76],{},"Reference"," — tables, configuration options, API endpoints",[48,79,80,83],{},[27,81,82],{},"Troubleshooting"," — common errors and fixes",[48,85,86,89],{},[27,87,88],{},"Changelog or version notes"," — when details change between versions",[10,91,92,93,96,97,100,101,103,104,107],{},"Use ",[14,94,95],{},"##"," headings for major sections and ",[14,98,99],{},"###"," for subsections. Avoid going deeper than ",[14,102,99],{}," — if you need ",[14,105,106],{},"####",", consider splitting the document.",[19,109,111],{"id":110},"formatting-for-readability","Formatting for Readability",[10,113,114],{},"Technical readers scan before they read. Format your Markdown to support scanning:",[116,117,118,124,134,148,154],"ul",{},[48,119,120,123],{},[27,121,122],{},"Use tables for comparisons and configuration options"," — they align information vertically, which is faster to parse than paragraphs",[48,125,126,129,130,133],{},[27,127,128],{},"Use code blocks for everything that belongs in a terminal or editor"," — inline code (",[14,131,132],{},"backticks",") for commands, file names, and short values; fenced blocks for multi-line examples",[48,135,136,139,140,143,144,147],{},[27,137,138],{},"Use callouts for warnings and important notes"," — GitHub supports ",[14,141,142],{},"> [!NOTE]"," and ",[14,145,146],{},"> [!WARNING]"," syntax; other platforms use blockquotes with bold labels",[48,149,150,153],{},[27,151,152],{},"Use numbered lists for sequential steps"," — ordered lists signal \"do this, then this\"",[48,155,156,159],{},[27,157,158],{},"Use bullet lists for non-sequential items"," — unordered lists signal \"these are related but order does not matter\"",[161,162,167],"pre",{"className":163,"code":164,"language":165,"meta":166,"style":166},"language-markdown shiki shiki-themes github-light github-dark","> [!WARNING]\n> This operation is irreversible. Back up your database before running the migration.\n","markdown","",[14,168,169,177],{"__ignoreMap":166},[170,171,174],"span",{"class":172,"line":173},"line",1,[170,175,176],{},"> [!WARNING]\n",[170,178,180],{"class":172,"line":179},2,[170,181,182],{},"> This operation is irreversible. Back up your database before running the migration.\n",[10,184,185],{},"Keep paragraphs short — three to four lines maximum. Dense paragraphs in technical docs get skipped.",[19,187,189],{"id":188},"code-examples-that-actually-work","Code Examples That Actually Work",[10,191,192],{},"Code examples are the most valuable part of technical documentation — and the most likely to be wrong. Follow these rules:",[45,194,195,201,211,217],{},[48,196,197,200],{},[27,198,199],{},"Every code block must be runnable"," — copy-paste should produce the described result without hidden dependencies",[48,202,203,206,207,210],{},[27,204,205],{},"Include the language identifier"," in the fence — ",[14,208,209],{},"```javascript"," enables syntax highlighting and tells readers what language to expect",[48,212,213,216],{},[27,214,215],{},"Show input and output"," — when describing a function, show both the call and the result",[48,218,219,222],{},[27,220,221],{},"Annotate complex lines"," — use comments inside the code block instead of explaining below it",[161,224,228],{"className":225,"code":226,"language":227,"meta":166,"style":166},"language-python shiki shiki-themes github-light github-dark","# Fetch user by ID — raises NotFoundError if the user does not exist\nuser = client.get_user(user_id=42)\n\n# Returns: User(name=\"Alice\", role=\"admin\", created_at=\"2025-01-15\")\n","python",[14,229,230,235,240,247],{"__ignoreMap":166},[170,231,232],{"class":172,"line":173},[170,233,234],{},"# Fetch user by ID — raises NotFoundError if the user does not exist\n",[170,236,237],{"class":172,"line":179},[170,238,239],{},"user = client.get_user(user_id=42)\n",[170,241,243],{"class":172,"line":242},3,[170,244,246],{"emptyLinePlaceholder":245},true,"\n",[170,248,250],{"class":172,"line":249},4,[170,251,252],{},"# Returns: User(name=\"Alice\", role=\"admin\", created_at=\"2025-01-15\")\n",[45,254,256],{"start":255},5,[48,257,258,261],{},[27,259,260],{},"Version your examples"," — if your library's API changed between versions, label code blocks with the version they apply to",[19,263,265],{"id":264},"diagrams-and-visual-documentation","Diagrams and Visual Documentation",[10,267,268],{},"Plain Markdown does not support diagrams, but several extensions fill the gap:",[270,271,272,288],"table",{},[273,274,275],"thead",{},[276,277,278,282,285],"tr",{},[279,280,281],"th",{},"Tool",[279,283,284],{},"Syntax",[279,286,287],{},"Renders In",[289,290,291,306,319,330],"tbody",{},[276,292,293,297,303],{},[294,295,296],"td",{},"Mermaid",[294,298,299,302],{},[14,300,301],{},"```mermaid"," code fences",[294,304,305],{},"GitHub, GitLab, Notion, many Markdown editors",[276,307,308,311,316],{},[294,309,310],{},"PlantUML",[294,312,313,302],{},[14,314,315],{},"```plantuml",[294,317,318],{},"GitLab, some VS Code extensions",[276,320,321,324,327],{},[294,322,323],{},"ASCII art",[294,325,326],{},"Plain text",[294,328,329],{},"Anywhere",[276,331,332,335,338],{},[294,333,334],{},"Excalidraw",[294,336,337],{},"Separate file + embed",[294,339,340],{},"Notion, custom setups",[10,342,343],{},"Mermaid is the most portable choice. It supports flowcharts, sequence diagrams, class diagrams, and Gantt charts:",[161,345,347],{"className":163,"code":346,"language":165,"meta":166,"style":166},"```mermaid\nsequenceDiagram\n    Client->>API: POST \u002Fusers\n    API->>DB: INSERT user\n    DB-->>API: user_id\n    API-->>Client: 201 Created\n`` ` \n",[14,348,349,354,359,364,369,374,380],{"__ignoreMap":166},[170,350,351],{"class":172,"line":173},[170,352,353],{},"```mermaid\n",[170,355,356],{"class":172,"line":179},[170,357,358],{},"sequenceDiagram\n",[170,360,361],{"class":172,"line":242},[170,362,363],{},"    Client->>API: POST \u002Fusers\n",[170,365,366],{"class":172,"line":249},[170,367,368],{},"    API->>DB: INSERT user\n",[170,370,371],{"class":172,"line":255},[170,372,373],{},"    DB-->>API: user_id\n",[170,375,377],{"class":172,"line":376},6,[170,378,379],{},"    API-->>Client: 201 Created\n",[170,381,383],{"class":172,"line":382},7,[170,384,385],{},"`` `\n",[10,387,388],{},"For simple relationships, ASCII diagrams work everywhere and require zero tooling.",[19,390,392],{"id":391},"api-reference-format","API Reference Format",[10,394,395],{},"API documentation in Markdown follows a consistent pattern. For each endpoint:",[161,397,399],{"className":163,"code":398,"language":165,"meta":166,"style":166},"### POST \u002Fapi\u002Fusers\n\nCreates a new user account.\n\n**Request body:**\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `name` | string | Yes | Display name (3–50 characters) |\n| `email` | string | Yes | Valid email address |\n| `role` | string | No | Defaults to `\"viewer\"` |\n\n**Response:** `201 Created`\n\n```json\n{\n  \"id\": \"usr_abc123\",\n  \"name\": \"Alice\",\n  \"role\": \"viewer\"\n}\n",[14,400,401,406,410,415,419,424,428,433,439,445,451,457,462,468,473,479,485,491,497,503],{"__ignoreMap":166},[170,402,403],{"class":172,"line":173},[170,404,405],{},"### POST \u002Fapi\u002Fusers\n",[170,407,408],{"class":172,"line":179},[170,409,246],{"emptyLinePlaceholder":245},[170,411,412],{"class":172,"line":242},[170,413,414],{},"Creates a new user account.\n",[170,416,417],{"class":172,"line":249},[170,418,246],{"emptyLinePlaceholder":245},[170,420,421],{"class":172,"line":255},[170,422,423],{},"**Request body:**\n",[170,425,426],{"class":172,"line":376},[170,427,246],{"emptyLinePlaceholder":245},[170,429,430],{"class":172,"line":382},[170,431,432],{},"| Field | Type | Required | Description |\n",[170,434,436],{"class":172,"line":435},8,[170,437,438],{},"|-------|------|----------|-------------|\n",[170,440,442],{"class":172,"line":441},9,[170,443,444],{},"| `name` | string | Yes | Display name (3–50 characters) |\n",[170,446,448],{"class":172,"line":447},10,[170,449,450],{},"| `email` | string | Yes | Valid email address |\n",[170,452,454],{"class":172,"line":453},11,[170,455,456],{},"| `role` | string | No | Defaults to `\"viewer\"` |\n",[170,458,460],{"class":172,"line":459},12,[170,461,246],{"emptyLinePlaceholder":245},[170,463,465],{"class":172,"line":464},13,[170,466,467],{},"**Response:** `201 Created`\n",[170,469,471],{"class":172,"line":470},14,[170,472,246],{"emptyLinePlaceholder":245},[170,474,476],{"class":172,"line":475},15,[170,477,478],{},"```json\n",[170,480,482],{"class":172,"line":481},16,[170,483,484],{},"{\n",[170,486,488],{"class":172,"line":487},17,[170,489,490],{},"  \"id\": \"usr_abc123\",\n",[170,492,494],{"class":172,"line":493},18,[170,495,496],{},"  \"name\": \"Alice\",\n",[170,498,500],{"class":172,"line":499},19,[170,501,502],{},"  \"role\": \"viewer\"\n",[170,504,506],{"class":172,"line":505},20,[170,507,508],{},"}\n",[10,510,511],{},[27,512,513],{},"Errors:",[270,515,516,529],{},[273,517,518],{},[276,519,520,523,526],{},[279,521,522],{},"Status",[279,524,525],{},"Code",[279,527,528],{},"When",[289,530,531,544],{},[276,532,533,536,541],{},[294,534,535],{},"400",[294,537,538],{},[14,539,540],{},"INVALID_EMAIL",[294,542,543],{},"Email format is invalid",[276,545,546,549,554],{},[294,547,548],{},"409",[294,550,551],{},[14,552,553],{},"EMAIL_EXISTS",[294,555,556],{},"Email already registered",[161,558,563],{"className":559,"code":561,"language":562},[560],"language-text","\nThis format lets readers scan the table for the field they need, then read the examples for context.\n\n## Maintaining Living Documentation\n\nDocumentation rots. Code changes, APIs evolve, screenshots go stale. A sustainable documentation system needs maintenance built into the workflow:\n\n- **Tie docs to code** — store `.md` files next to the code they describe in the same repository\n- **Enforce doc reviews** — require documentation updates in the same PR that changes behavior\n- **Use CI checks** — lint Markdown files with `markdownlint`, validate links with `lychee` or `linkcheck`\n- **Add freshness dates** — include a `last-reviewed` date in frontmatter; CI can flag docs older than 90 days\n- **Generate what you can** — API references, type definitions, and configuration tables can be auto-generated from code\n\n## Key Takeaways\n\n- Structure docs as: what → how → why, with quick start before deep explanation\n- Format for scanning — short paragraphs, tables for comparisons, code blocks with language identifiers\n- Every code example must be runnable — hidden dependencies destroy trust\n- Use Mermaid for diagrams when your platform supports it; ASCII works everywhere\n- Treat documentation as code — review it in PRs, lint it in CI, and track freshness dates\n\n## Related Guides\n\n- [Markdown Preview: Real-Time Rendering for Your Documents](\u002Fguides\u002Fmarkdown-preview-guide)\n- [Markdown Writing Workflow: From Draft to Published](\u002Fguides\u002Fmarkdown-writing-workflow)\n- [GitHub Flavored Markdown: Extensions and Syntax Guide](\u002Fguides\u002Fgithub-flavored-markdown)\n\n## Try It Yourself\n\nWrite and preview your technical docs with our free [Markdown Preview](\u002Ftools\u002Fmarkdown-preview) tool. Paste your Markdown, see the rendered output instantly, and catch formatting issues before publishing.\n","text",[14,564,561],{"__ignoreMap":166},[566,567,568],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":166,"searchDepth":179,"depth":179,"links":570},[571,572,573,574,575],{"id":21,"depth":179,"text":22},{"id":110,"depth":179,"text":111},{"id":188,"depth":179,"text":189},{"id":264,"depth":179,"text":265},{"id":391,"depth":179,"text":392},"2026-05-28","Best practices for writing technical docs in Markdown — structure, formatting, diagrams, API references, and maintaining a living documentation system.","md",{"immutable":245},"\u002Fguides\u002Fwriting-technical-docs-markdown",{"title":5,"description":577},"guides\u002Fwriting-technical-docs-markdown","oyGixkpbrOmGaSrrVOR_ta9k4qoRjiln2pvj2oSYD3g",1780401338381]