[{"data":1,"prerenderedAt":484},["ShallowReactive",2],{"guide-writing-concise-documentation":3},{"id":4,"title":5,"body":6,"date":476,"description":477,"extension":478,"meta":479,"navigation":68,"path":480,"readingTime":117,"seo":481,"stem":482,"__hash__":483},"guides\u002Fguides\u002Fwriting-concise-documentation.md","Writing Concise Documentation: Say More with Fewer Words",{"type":7,"value":8,"toc":456},"minimark",[9,14,18,21,25,30,33,76,79,83,86,133,136,144,147,151,154,209,212,216,219,253,256,260,263,292,295,299,303,306,310,313,317,320,324,327,331,334,338,341,408,412,434,438,447,452],[10,11,13],"h2",{"id":12},"concise-documentation-saves-everyone-time","Concise Documentation Saves Everyone Time",[15,16,17],"p",{},"Developers read documentation to solve problems quickly. Every unnecessary word adds friction. Concise writing is not about removing detail — it is about presenting the right detail efficiently. When you write less, readers understand more.",[15,19,20],{},"This guide provides actionable techniques for cutting documentation length while improving clarity.",[10,22,24],{"id":23},"principle-1-lead-with-the-answer","Principle 1: Lead With the Answer",[26,27,29],"h3",{"id":28},"pattern-problem-explanation-answer","Pattern: Problem → Explanation → Answer",[15,31,32],{},"Many documentation writers build up to the answer. Readers want the answer first.",[34,35,40],"pre",{"className":36,"code":37,"language":38,"meta":39,"style":39},"language-markdown shiki shiki-themes github-light github-dark","❌ When working with arrays in JavaScript, you may encounter situations where\nyou need to transform each element. The `map()` method creates a new array\nby applying a function to every element of the original array.\n\n✅ Use `Array.map()` to transform every element in an array:\n","markdown","",[41,42,43,51,57,63,70],"code",{"__ignoreMap":39},[44,45,48],"span",{"class":46,"line":47},"line",1,[44,49,50],{},"❌ When working with arrays in JavaScript, you may encounter situations where\n",[44,52,54],{"class":46,"line":53},2,[44,55,56],{},"you need to transform each element. The `map()` method creates a new array\n",[44,58,60],{"class":46,"line":59},3,[44,61,62],{},"by applying a function to every element of the original array.\n",[44,64,66],{"class":46,"line":65},4,[44,67,69],{"emptyLinePlaceholder":68},true,"\n",[44,71,73],{"class":46,"line":72},5,[44,74,75],{},"✅ Use `Array.map()` to transform every element in an array:\n",[15,77,78],{},"The concise version states the solution immediately. Context follows only if needed.",[26,80,82],{"id":81},"pattern-beforeafter-statements","Pattern: Before\u002FAfter Statements",[15,84,85],{},"When documenting a change or migration, show the result before explaining why:",[34,87,89],{"className":36,"code":88,"language":38,"meta":39,"style":39},"❌ The old configuration format used YAML, but we've migrated to TOML\nfor better type support. Your config file should now look like this:\n\n✅ Configuration is now TOML:\n```toml\n[database]\nhost = \"localhost\"\nport = 5432\n",[41,90,91,96,101,105,110,115,121,127],{"__ignoreMap":39},[44,92,93],{"class":46,"line":47},[44,94,95],{},"❌ The old configuration format used YAML, but we've migrated to TOML\n",[44,97,98],{"class":46,"line":53},[44,99,100],{},"for better type support. Your config file should now look like this:\n",[44,102,103],{"class":46,"line":59},[44,104,69],{"emptyLinePlaceholder":68},[44,106,107],{"class":46,"line":65},[44,108,109],{},"✅ Configuration is now TOML:\n",[44,111,112],{"class":46,"line":72},[44,113,114],{},"```toml\n",[44,116,118],{"class":46,"line":117},6,[44,119,120],{},"[database]\n",[44,122,124],{"class":46,"line":123},7,[44,125,126],{},"host = \"localhost\"\n",[44,128,130],{"class":46,"line":129},8,[44,131,132],{},"port = 5432\n",[15,134,135],{},"Previously this was YAML. See Migration Guide for details.",[34,137,142],{"className":138,"code":140,"language":141},[139],"language-text","\n## Principle 2: Eliminate Filler Phrases\n\nThese phrases add words without adding information:\n\n| Filler Phrase | Concise Replacement |\n|--------------|-------------------|\n| \"In order to\" | \"To\" |\n| \"It is important to note that\" | Remove entirely |\n| \"As a matter of fact\" | Remove entirely |\n| \"Due to the fact that\" | \"Because\" |\n| \"At this point in time\" | \"Now\" |\n| \"For the purpose of\" | \"To\" |\n| \"In the event that\" | \"If\" |\n| \"There is\u002Fare\" | Restructure |\n| \"It should be noted that\" | Remove entirely |\n\n### Example\n\n```markdown\n❌ It is important to note that in order to configure the database,\nyou need to ensure that the connection string is set in the event\nthat you are using a remote server.\n\n✅ Set the connection string for remote database connections.\n","text",[41,143,140],{"__ignoreMap":39},[15,145,146],{},"Three sentences become one. The meaning is identical.",[10,148,150],{"id":149},"principle-3-use-lists-instead-of-paragraphs","Principle 3: Use Lists Instead of Paragraphs",[15,152,153],{},"Lists are scannable. Paragraphs are not. When you have three or more related items, use a list.",[34,155,157],{"className":36,"code":156,"language":38,"meta":39,"style":39},"❌ The API supports several authentication methods including API keys,\nOAuth 2.0 bearer tokens, and HMAC signatures. API keys are the simplest\nto implement. OAuth 2.0 is recommended for user-facing applications.\nHMAC signatures provide the highest security for server-to-server calls.\n\n✅ Supported authentication methods:\n\n- **API keys** — simplest to implement\n- **OAuth 2.0** — recommended for user-facing apps\n- **HMAC signatures** — highest security for server-to-server calls\n",[41,158,159,164,169,174,179,183,188,192,197,203],{"__ignoreMap":39},[44,160,161],{"class":46,"line":47},[44,162,163],{},"❌ The API supports several authentication methods including API keys,\n",[44,165,166],{"class":46,"line":53},[44,167,168],{},"OAuth 2.0 bearer tokens, and HMAC signatures. API keys are the simplest\n",[44,170,171],{"class":46,"line":59},[44,172,173],{},"to implement. OAuth 2.0 is recommended for user-facing applications.\n",[44,175,176],{"class":46,"line":65},[44,177,178],{},"HMAC signatures provide the highest security for server-to-server calls.\n",[44,180,181],{"class":46,"line":72},[44,182,69],{"emptyLinePlaceholder":68},[44,184,185],{"class":46,"line":117},[44,186,187],{},"✅ Supported authentication methods:\n",[44,189,190],{"class":46,"line":123},[44,191,69],{"emptyLinePlaceholder":68},[44,193,194],{"class":46,"line":129},[44,195,196],{},"- **API keys** — simplest to implement\n",[44,198,200],{"class":46,"line":199},9,[44,201,202],{},"- **OAuth 2.0** — recommended for user-facing apps\n",[44,204,206],{"class":46,"line":205},10,[44,207,208],{},"- **HMAC signatures** — highest security for server-to-server calls\n",[15,210,211],{},"The list version is 40% shorter and easier to scan.",[10,213,215],{"id":214},"principle-4-one-idea-per-sentence","Principle 4: One Idea Per Sentence",[15,217,218],{},"Long sentences with multiple clauses force re-reading. Break them apart.",[34,220,222],{"className":36,"code":221,"language":38,"meta":39,"style":39},"❌ The linter checks your code for style violations and will\nautomatically fix issues when you pass the --fix flag, although\nsome violations require manual intervention.\n\n✅ The linter checks for style violations. Pass `--fix` to auto-fix\nmost issues. Some violations require manual fixes.\n",[41,223,224,229,234,239,243,248],{"__ignoreMap":39},[44,225,226],{"class":46,"line":47},[44,227,228],{},"❌ The linter checks your code for style violations and will\n",[44,230,231],{"class":46,"line":53},[44,232,233],{},"automatically fix issues when you pass the --fix flag, although\n",[44,235,236],{"class":46,"line":59},[44,237,238],{},"some violations require manual intervention.\n",[44,240,241],{"class":46,"line":65},[44,242,69],{"emptyLinePlaceholder":68},[44,244,245],{"class":46,"line":72},[44,246,247],{},"✅ The linter checks for style violations. Pass `--fix` to auto-fix\n",[44,249,250],{"class":46,"line":117},[44,251,252],{},"most issues. Some violations require manual fixes.\n",[15,254,255],{},"Each sentence carries one idea. The reader processes each step before moving to the next.",[10,257,259],{"id":258},"principle-5-active-voice","Principle 5: Active Voice",[15,261,262],{},"Passive voice hides the actor and adds words:",[34,264,266],{"className":36,"code":265,"language":38,"meta":39,"style":39},"❌ The configuration file is parsed by the application on startup.\n✅ The application parses the configuration file on startup.\n\n❌ It is recommended that HTTPS be used in production.\n✅ Use HTTPS in production.\n",[41,267,268,273,278,282,287],{"__ignoreMap":39},[44,269,270],{"class":46,"line":47},[44,271,272],{},"❌ The configuration file is parsed by the application on startup.\n",[44,274,275],{"class":46,"line":53},[44,276,277],{},"✅ The application parses the configuration file on startup.\n",[44,279,280],{"class":46,"line":59},[44,281,69],{"emptyLinePlaceholder":68},[44,283,284],{"class":46,"line":65},[44,285,286],{},"❌ It is recommended that HTTPS be used in production.\n",[44,288,289],{"class":46,"line":72},[44,290,291],{},"✅ Use HTTPS in production.\n",[15,293,294],{},"Active voice is shorter and clearer. Reserve passive voice for when the actor genuinely doesn't matter.",[10,296,298],{"id":297},"practical-editing-workflow","Practical Editing Workflow",[26,300,302],{"id":301},"pass-1-cut-filler","Pass 1: Cut Filler",[15,304,305],{},"Search for the filler phrases listed above. Remove or replace each one.",[26,307,309],{"id":308},"pass-2-convert-paragraphs-to-lists","Pass 2: Convert Paragraphs to Lists",[15,311,312],{},"Find any paragraph with three or more parallel items. Convert to a bulleted list.",[26,314,316],{"id":315},"pass-3-shorten-sentences","Pass 3: Shorten Sentences",[15,318,319],{},"Find sentences over 25 words. Split them.",[26,321,323],{"id":322},"pass-4-eliminate-redundancy","Pass 4: Eliminate Redundancy",[15,325,326],{},"Find repeated information. Keep it once, in the most relevant section.",[26,328,330],{"id":329},"pass-5-verify-completeness","Pass 5: Verify Completeness",[15,332,333],{},"After cutting, re-read to ensure no essential information was removed. Concise writing must remain accurate.",[10,335,337],{"id":336},"measuring-conciseness","Measuring Conciseness",[15,339,340],{},"Track your documentation's density with these metrics:",[342,343,344,360],"table",{},[345,346,347],"thead",{},[348,349,350,354,357],"tr",{},[351,352,353],"th",{},"Metric",[351,355,356],{},"Target",[351,358,359],{},"Tool",[361,362,363,375,386,397],"tbody",{},[348,364,365,369,372],{},[366,367,368],"td",{},"Average sentence length",[366,370,371],{},"15-20 words",[366,373,374],{},"Word counter",[348,376,377,380,383],{},[366,378,379],{},"Paragraph length",[366,381,382],{},"3-4 sentences",[366,384,385],{},"Manual",[348,387,388,391,394],{},[366,389,390],{},"Filler word ratio",[366,392,393],{},"\u003C 5%",[366,395,396],{},"Text analysis",[348,398,399,402,405],{},[366,400,401],{},"Time to first answer",[366,403,404],{},"\u003C 30 seconds",[366,406,407],{},"User testing",[10,409,411],{"id":410},"key-takeaways","Key Takeaways",[413,414,415,419,422,425,428,431],"ul",{},[416,417,418],"li",{},"Lead with the answer — readers scan, they don't read linearly",[416,420,421],{},"Eliminate filler phrases like \"in order to\" and \"it is important to note\"",[416,423,424],{},"Convert paragraphs with 3+ items into scannable lists",[416,426,427],{},"One idea per sentence — split long sentences at conjunctions",[416,429,430],{},"Prefer active voice for shorter, clearer sentences",[416,432,433],{},"Follow a structured editing workflow: cut filler, convert to lists, shorten sentences, remove redundancy, verify completeness",[10,435,437],{"id":436},"try-it-yourself","Try It Yourself",[15,439,440,441,446],{},"Measure and improve your documentation's conciseness with our free ",[442,443,445],"a",{"href":444},"\u002Ftools\u002Fword-counter","Word Counter",". Paste any text to instantly see word count, character count, average sentence length, and estimated reading time — all processed locally in your browser.",[15,448,449],{},[442,450,451],{"href":444},"Try the Word Counter →",[453,454,455],"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":39,"searchDepth":53,"depth":53,"links":457},[458,459,463,464,465,466,473,474,475],{"id":12,"depth":53,"text":13},{"id":23,"depth":53,"text":24,"children":460},[461,462],{"id":28,"depth":59,"text":29},{"id":81,"depth":59,"text":82},{"id":149,"depth":53,"text":150},{"id":214,"depth":53,"text":215},{"id":258,"depth":53,"text":259},{"id":297,"depth":53,"text":298,"children":467},[468,469,470,471,472],{"id":301,"depth":59,"text":302},{"id":308,"depth":59,"text":309},{"id":315,"depth":59,"text":316},{"id":322,"depth":59,"text":323},{"id":329,"depth":59,"text":330},{"id":336,"depth":53,"text":337},{"id":410,"depth":53,"text":411},{"id":436,"depth":53,"text":437},"2026-05-28","Learn practical techniques for writing concise technical documentation. Reduce word count without losing clarity using active voice, structure, and editing patterns.","md",{"immutable":68},"\u002Fguides\u002Fwriting-concise-documentation",{"title":5,"description":477},"guides\u002Fwriting-concise-documentation","7-5hh0bx9eS5eUzOPXU2bYzF4cnDxRWsq79CcRpU_2Y",1780401338334]