Skip to content
Search

Documentation

lastmod 2026-11-02created 2021-01-2223 edits

A set of techniques for smoothly providing information that has been organized, systematized, and recorded as needed for research and the like. Collecting, classifying, indexing, and abstracting information, information retrieval, etc. Information management.

Categories

Rules for writing software tutorials

  • Rules for Writing Software Tutorials · Refactoring English
  • Most software tutorials leave out important details or contain hidden assumptions that don't match the reader's expectations, so the reader can't reproduce the process
  • Following a few simple rules makes writing an excellent tutorial easier than you might think

Rules:

  1. Write for beginners
  2. Write a title that promises a clear outcome
  3. Explain the goal in the introduction
  4. Show the end result up front
  5. Write copy/pasteable code snippets
  6. Use long flags in commands
  7. Separate user-defined values from reusable logic
  8. Spare the reader's effort
  9. Keep the code in a working state at all times
  10. Teach one topic only
  11. Clarity over decoration
  12. Minimize dependencies
  13. Specify file names clearly
  14. Use consistent, descriptive headings
  15. Prove that the solution works
  16. Link to a complete example

Write for beginners

  • The most common tutorial mistake is explaining beginner-level concepts in expert-level terms. Most people looking for tutorials are beginners.
    • They may not be beginners at programming, but they are beginners in the domain they want to learn
  • Write for beginners and avoid expert-level terminology
  • Avoid difficult terms and write in simple language the reader can understand
  • For example, in a React tutorial, describe it as "creating a simple web page with React" instead of "JSX transpilation"

Write a title that promises a clear outcome

  • The title should tell the reader specifically what they can learn from the tutorial
  • Avoid unclear or vague titles, and state the expected outcome clearly
    • e.g., "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView"

Explain the goal in the introduction

  • If a reader clicks on your tutorial, they are interested in what you have to say. But you still have to persuade them to keep reading
  • The reader wants to know two things
    • Should I care about this technology?
    • If so, is this tutorial right for me?
  • In the introduction, briefly explain why the technology matters and how the tutorial is useful
  • Give useful information to draw the reader in, and avoid vague statements
    • e.g., a Docker tutorial clearly explains the problem Docker solves and the expected outcome

Show the end result up front

  • As early as possible, show a working demo or screenshot of what the reader will build in the tutorial
    • Showing the end result early in the tutorial makes the goal clear
  • e.g., provide screenshots of the final product, the UI, working examples, etc.

Write copy/pasteable code snippets

  • Write code so the reader can easily copy it and paste it into an editor or terminal to run it
  • Remove unnecessary elements such as the terminal prompt character $
  • Use non-interactive flags to simplify commands, and use && so they stop on failure

Use long flags in commands

  • In commands, use clearly descriptive long flags instead of short flags so that beginners can understand them easily
    • --recursive rather than -r

Separate user-defined values from reusable logic

  • Clearly separate the values the user needs to change from the code they should not change
  • Use environment variables to define user-defined values and improve the readability of the code

Spare the reader's effort

  • Respect the reader's time so they come to like the tutorial
  • Replace tedious work with command snippets
    • e.g., solve it with a command instead of editing a file by hand

Keep the code in a working state at all times

  • Example code should always be runnable, and stay in a working state even at intermediate steps
  • Broken code or non-working examples confuse the reader

Teach one topic only

  • Build the tutorial around a single topic, and don't mix in unrelated technologies
  • For example, don't add unnecessary AI technology to a tutorial that explains a search feature

Clarity over decoration

  • Readers don't care whether a toy application looks beautiful
  • Minimize unnecessary CSS and design elements, and focus on the core concepts
  • Convey concepts clearly with simple code rather than complex examples

Minimize dependencies

  • Minimize the dependencies the reader has to install to make the tutorial more accessible
  • Specify required dependencies clearly, including specific versions

Specify file names clearly

  • Tell the reader exactly which file paths and contents to change
  • For example, instead of "add a setting to the config file", give the full file path and concrete code showing exactly which line to edit

Use consistent, descriptive headings

  • Use structured headings so the reader can scan the tutorial easily
  • Use headings to structure the tutorial, and write them to reflect its logical structure
  • Keep the format, point of view, and tense of headings consistent

Prove that the solution works

  • If the tutorial teaches installing a tool or integrating several components, show how to use the result
    • Visually show the reader the installed and integrated tools working
  • For example, show the nginx success page and explain how to check it via a URL
  • Link to a repository containing all the code in the tutorial so the reader can see the whole flow
  • Split each step's code into a separate git branch so the reader can follow each step

Good writing

Good writing can have two aspects: "sentences that sound good" and "the right ideas"

  • Good writing has sentences that flow well, or carries the right ideas, or both
  • Pursuing natural-sounding sentences improves the accuracy and depth of the ideas at the same time
  • The constraints that come up while revising don't make the content worse; rather, they lead it in a better direction
  • Rhythmic sentence construction touches the essence of the ideas, producing writing that is easy to read and easy to review
  • The closer the match between content and expression, the greater the coherence and truthfulness, and in the end the two are connected as one

A collection of clichéd patterns to avoid in AI writing

  • A collection of clichéd patterns to avoid in AI writing | GeekNews
  • A single Markdown file that classifies, by category, the writing patterns (tropes) that recur in AI-generated text
  • Adding this file to an AI system prompt can steer it away from common AI-style prose
  • Organizes 30+ specific patterns, each with examples, under 6 major categories: word choice, sentence structure, paragraph structure, tone, formatting, and composition
  • Covers everything from AI-specific overused vocabulary like "delve", "tapestry", and "landscape" to sentence structures that create false profundity, like "It's not X -- it's Y"
  • Each pattern is fine once or twice, but when several patterns appear together or repeatedly, they become a strong signal of AI-generated text
  • The file itself was also written with AI assistance, and includes the disclaimer "AI for AI, humans for humans"

Word Choice

  • "Quietly" and magic adverbs: overusing adverbs like "quietly", "deeply", "fundamentally", "remarkably", and "arguably" to lend subtle significance to ordinary descriptions
    • e.g., "quietly orchestrating workflows", "a quiet intelligence behind it"
  • "Delve" and friends: once the most famous AI tell, a word that appears with abnormally high frequency in AI-generated text
    • "certainly", "utilize", "leverage" (verb), "robust", "streamline", "harness", etc. belong to the same family
  • "Tapestry" and "Landscape": using grandiose nouns where a simple word would do
    • "tapestry" is overused for anything interconnected, "landscape" for any field or domain
    • "paradigm", "synergy", "ecosystem", and "framework" are the same type
  • "Serves As" avoidance: using inflated linking phrases like "serves as", "stands as", "marks", or "represents" instead of a simple "is/are"
    • Happens because AI repetition penalties push away from the basic copula toward fancier constructions

Sentence Structure

  • Negative Parallelism: the "It's not X -- it's Y" pattern, the most commonly identified tell of AI writing
    • Wraps everything as a surprising reframe, creating false profundity
    • Mass writing in this style did not exist before LLMs
    • Also includes the causal variant "not because X, but because Y"
  • "Not X. Not Y. Just Z.": a dramatic countdown pattern that negates two or more things before revealing the real point
    • Creates a false sense of narrowing in on the truth
  • "The X? A Y.": a rhetorical question-and-instant-answer pattern that poses a question nobody asked and answers it right away
    • Used for dramatic effect; AI treats it as the essence of great writing
  • Anaphora abuse: repeating the same sentence opening several times in quick succession
    • e.g., "They assume that... They assume that... They assume that..."
  • Tricolon abuse: overusing the rule of three, including stretching it to four or five
    • One tricolon is elegant, but three in a row is a failure of pattern recognition
  • "It's Worth Noting": filler transitions that signal nothing
    • "It bears mentioning", "Importantly", "Interestingly", and "Notably" are the same type
    • Introduces a new point without actually connecting it to the previous argument
  • Superficial Analyses: tacking a present participle ("-ing") phrase onto the end of a sentence to inject shallow analysis
    • Expressions like "highlighting its importance", "reflecting broader trends", "contributing to the development of..."
    • Attributes significance, legacy, and broad meaning to ordinary facts
  • False Ranges: "from X to Y" constructions where X and Y do not actually sit on any scale
    • Legitimate use implies a spectrum with meaningful midpoints, but AI uses it to list two loosely related things
  • Gerund Fragment Litany: after a claim, listing a string of subjectless gerund fragments
    • "Fixing small bugs. Writing straightforward features. Implementing well-defined tickets."
    • The first sentence already said it all; the fragments only add word count and AI-specific rhythm
    • Humans don't write first drafts this way; it is a pure structural tic

Paragraph Structure

  • Short Punchy Fragments: using very short sentences or sentence fragments as standalone paragraphs to create artificial emphasis
    • The result of RLHF training pushing models toward "writing for readability" aimed at the lowest-level reader
    • One thought per sentence, an inhuman style that needs no mental state to be maintained
  • Listicle in a Trench Coat: disguising numbered or labeled points as continuous prose
    • A pattern that hides list format in paragraphs starting with "The first... The second... The third..."
    • Often adopted as a workaround after being told to stop generating lists

Tone

  • "Here's the Kicker": a false-suspense transition that promises a revelation but delivers a point that didn't need the buildup
    • "Here's the thing", "Here's where it gets interesting", and "Here's what most people miss" are the same type
  • "Think of It As...": a teacher-mode default that assumes the reader needs an analogy to understand anything
    • AI frequently produces analogies less clear than the original concept
  • "Imagine a World Where...": AI's typical futurist invitation; "Imagine" is followed by a list of wonderful things that would happen if you accepted the premise
  • False Vulnerability: performative self-awareness that pretends to break the fourth wall or admit bias
    • Real vulnerability is specific and uncomfortable, but AI's vulnerability is polished and risk-free
  • "The Truth Is Simple": asserting that something is obvious or simple instead of actually proving it
  • Grandiose Stakes Inflation: inflating the stakes of every point to world-historical importance
    • A blog post about API pricing turns into a meditation on the fate of civilization
  • "Let's Break This Down": a pedagogical voice that defaults to a teacher-student relationship even with expert readers
    • "Let's unpack this", "Let's explore", and "Let's dive in" are the same type
  • Vague Attributions: attributing claims to unnamed authorities like "experts", "observers", or "industry reports" without specific sources
    • Also includes presenting what one person said as a widely held view, or inflating two sources into "several publications"
  • Invented Concept Labels: attaching abstract problem nouns (paradox, trap, creep, divide, vacuum, inversion) to domain words to create compound labels that sound analytical but have no grounding
    • "supervision paradox", "acceleration trap", "workload creep", etc.
    • Works as rhetorical shorthand that names something and skips the argument; several in the same piece is a strong signal of AI slop

Formatting

  • Em-Dash Addiction: compulsively overusing em dashes for dramatic pauses, parentheticals, and pivots
    • Human writers naturally use 2-3 in a piece, but AI uses 20 or more
  • Bold-First Bullets: every bullet point starts with a bold phrase
    • Very common in Claude and ChatGPT Markdown output; almost nobody formats this way when writing by hand
    • A sure sign of AI-generated documents, blog posts, and README files (especially with emoji)
  • Unicode Decoration: using special characters not easily typed on a standard keyboard, such as Unicode arrows (→) and smart/curly quotes
    • Real writers use straight quotes and ->, => in text editors
    • Claude especially favors the → arrow

Composition

  • Fractal Summaries: applying "what I'm about to say, what I'm saying, what I just said" at every level of the document
    • Every subsection, section, and the document itself each get a summary
  • The Dead Metaphor: latching onto one metaphor and using it repeatedly throughout the piece
    • Human writers introduce a metaphor, use it, and move on, but AI repeats it 5-10 times
  • Historical Analogy Stacking: especially common in tech writing; rapidly listing historical companies or technological revolutions to build false authority
    • Patterns like "Apple didn't build Uber. Facebook didn't build Spotify..."
  • One-Point Dilution: restating a single point in 10 different ways over thousands of words
    • Padding to look "comprehensive" by repeating the same idea with different analogies, examples, and framings
  • Content Duplication: repeating whole sections or paragraphs verbatim within the same piece
    • Happens when the model loses track of what it has already written, especially in long pieces
    • A sure sign of unedited AI output, but less common recently
  • The Signposted Conclusion: explicitly announcing the conclusion with "In conclusion", "To sum up", or "In summary"
    • Skilled writing lets the reader feel the conclusion without having to announce it
    • Signals the structural move because AI follows a template
  • "Despite Its Challenges...": a rigid formula in which AI acknowledges problems but immediately dismisses them
    • Always follows the same beat: "Despite its [positive word], [subject] faces challenges..." then "Despite these challenges, [optimistic conclusion]"

Core principles

  • Each of the patterns above may be fine used once, but becomes a problem when several appear together or one is used repeatedly
  • Write like a human: varied, imperfect, and specific

How to write better: a practical guide for developers

For software engineers, writing is more than a means of communication; it is an important skill for career growth. Writing ability matters more the more people a role affects, as with senior engineers, staff engineers, and engineering managers.

Developers spend more time writing than they think. They write as much text as code: commit messages, code reviews, design documents, incident retrospectives, project proposals, emails, and more, and clear writing becomes a way to extend their influence beyond the team.

How to write well

  • Go through drafting, editing, and feedback: good writing isn't complete from the start; it is the result of refining it several times
  • Break it into easy-to-read units: put one idea in each paragraph, and cut long sentences and unnecessary expressions
  • Review from the reader's point of view: check whether the reader has the background knowledge they need and can easily understand the message
  • Use lists and emphasis appropriately: structure the text so key information can be grasped quickly
  • Use figures and diagrams: in technical documents, visuals can be more effective than complex explanations
  • Value the reader's time more: the more people read a document, the more efficient it is overall for the author to spend more time polishing it

Habits for improving your writing

  • Observe and imitate good writing: collect well-written technical documents, project proposals, incident retrospectives, etc., and analyze what makes them effective
  • Ask for specific feedback: rather than just asking for opinions, ask whether any parts are hard to understand or unnecessary
  • Practice writing regularly: use weekly status reports, project progress updates, meeting notes, design documents, etc. as chances to practice
  • Invest more time in important documents: not every message needs to be perfectly polished, but widely shared documents should go through enough editing and feedback
  • Use writing tools and resources: keep learning with Hemingway Editor, Grammarly, Google's technical writing courses, etc.

Key message

Writing ability is not an innate talent but a skill that can be developed through deliberate practice and repetition.

Technical expertise alone has limits when it comes to influencing an entire organization. The ability to communicate your thoughts and decisions clearly, and to make others understand and use them, is what matters.

Combining technical skill with excellent writing ability is a powerful weapon that greatly increases an engineer's influence.

See also

Favorite site

Best Practices

author Zer0 sitemap