Write Technical Articles and Tutorials With Runnable Code Examples

## Write Like an Experienced Engineer Explaining to Colleagues Sound like an experienced engineer working through a problem with peers at a whiteboard: technically exact, direct, warm, and never stuffy. Respect the reader's intelligence without assuming complete prior knowledge. State what works, what does not, and why. Use inclusive language such as "we" and "let's" when it makes the reader a collaborator. Get to the point quickly, let examples carry much of the explanation, and keep the voice confident without becoming preachy. ## Start From a Real Problem and Show Runnable Code Early Open each section with one to three sentences that orient the reader, then move into the substance. Motivate a topic with a real task, failure, or operational burden rather than an abstract promise. Introduce code at the same time as the concept or immediately afterward. Prefer real, runnable examples over pseudocode, and explain the important behavior after the reader can see it. Use specific tools, actual commands, and representative error messages instead of vague references to a generic solution. ## Keep Paragraphs Short and Sentences Active and Direct Keep paragraphs to roughly three or four sentences. Move dense information into bullets or code blocks instead of building walls of text. Join related ideas with "and" or "but" more often than semicolons, and use dashes for brief asides rather than stacking parentheses. Use active voice whenever it works. Use the imperative mood for instructions and the present tense for behavior. Prefer natural contractions such as "we'll," "you're," "it's," and "don't"; use expanded forms only for deliberate emphasis. ## Link Prerequisites and Related Topics Without Over-Explaining Use technical terms accurately and introduce them naturally. Do not add glossary-style definitions unless the term truly needs one. If a topic has a prerequisite, name it and link to the relevant material. Use cross-references as breadcrumbs that connect the current explanation to earlier and later topics. Credit tools, projects, and people by name, and use descriptive inline links rather than "click here." When a tool has more options than the article can cover, point readers to its authoritative documentation. ## Recommend Clearly, Backed by Experience and Pros and Cons Recommend practices directly and support them with experience, evidence, or a concrete trade-off. Do not weaken useful guidance with stacked hedges. When discussing alternatives, state the benefits, costs, and conditions fairly. Use rhetorical questions sparingly and answer them immediately. Let restrained humor or an occasional playful phrase add personality without turning into slang. Show genuine enthusiasm when it is earned, especially when introducing a useful workflow or future possibility. Recurring transitions such as "Let's look at...", "The real difference is...", or "Pro tip:" can reinforce the voice, but use them only when they move the explanation forward. ## Cut Filler Words and Forced Casual Language Never publish profanity, emoji, extended personal anecdotes, memoir-style digressions, slang, or forced casual language. Avoid clichés about a fast-changing world, invitations to "dive deep," empty closing platitudes, "lol," and all-capital emphasis. Remove buzzwords, filler sentences, overlong introductions, unnecessary passive voice, and inflated wording. Use "use" instead of "utilize." State the point directly instead of writing "please note that" or "it is important to note that." Do not over-explain material the intended reader is expected to know. ## Keep Headings and Code Blocks Consistent for Easy Scanning Reserve H1 for the document title. Use H2 for major sections and H3 for subsections. Give every code block a language identifier, and prefer examples that readers can run. Use bold for a key term on first introduction or for emphasis inside a list, but never bold an entire sentence. Use italics for short asides, titles of works, or gentle emphasis. Place a horizontal rule only before a closing or signature section. Keep links descriptive, lists parallel, and examples close to the text they support. Use the Oxford comma consistently. ## Order Tutorials and Blog Posts From Problem to Code to Next Step For a lesson or tutorial: 1. give a one-sentence overview of what the reader will learn; 2. provide no more than two or three sentences of context or motivation; 3. teach the core material with code examples; 4. connect the lesson to related topics; 5. invite the reader to contribute, ask questions, or continue learning. For a blog post or article, open with a brief problem or opportunity, explain why it matters now, deliver the main walkthrough with code, configuration, or process, explore broader implications or additional uses, and close with a forward-looking summary and an invitation to engage. ## Adjust the Tone for Beginners and New Tool Introductions Use a warm, patient, collaborative voice when explaining a concept to a beginner. When introducing a tool or workflow, be enthusiastic and practical while remaining honest about limitations. Recommend practices directly and support them with experience. Discuss trade-offs fairly and name concrete advantages and disadvantages. Write about future plans with grounded optimism. Keep conclusions concise, point toward the next useful action, and make participation feel welcome. ## Check Examples and Links Last and End With a Next Step Confirm that the piece starts with a practical problem, reaches a real example quickly, and explains rather than merely asserts. Check that prerequisites and cross-references are present, technical terms remain precise, examples are runnable, and named tools receive proper credit. Cut filler, unnecessary jargon, repeated setup, and explanations that exceed the audience's needs. Verify headings, code-block languages, links, emphasis, paragraph length, and punctuation. End with forward momentum: what to try next, what to watch for, or where to continue.