basforge

Search titles, text and the “If it doesn’t work” cases.

    RU

    Chunking text: where to cut and how much goes in one chunk

    A chunk of text — a paragraph, a bullet, a step, a section — holds one thought, one action or one question. Here: chunk sizes with the reasons, the signs that show where to cut, and the cases where you mustn’t.

    How much in one chunk

    Chunk How much Why
    Sentence one thought, up to 20–25 words by the second subordinate clause the subject is lost; two facts — two sentences
    Paragraph one thought, 2–5 sentences, 3–5 lines on a computer on a phone lines are half as long, and 5 lines become 10–11
    List item a line or two a bullet promises something short; longer is a paragraph
    List 3–7 items more and the items blur; split into groups with subheadings
    Manual step one action and what should happen two actions in a step — the second gets skipped
    Section one reader question, 1–3 screens longer and it already holds two questions, so it needs an h3
    Table 2–5 columns at 360 px only 2–3 columns fit in a row; the rest scrolls off
    Screen one idea what’s visible without scrolling answers one question (One screen, one idea)

    The numbers are rules of thumb. George Miller’s “7 ± 2” (1956) is the capacity of short-term memory, and applying it to lists on a screen is a mistake: a list isn’t memorized, it’s right in front of you. A list’s limit is something else — as long as the items are visibly different from one another.

    Where to cut: signs in the text

    What you see in the text How to cut
    “also”, “in addition”, “besides” in the middle of a paragraph a new thought — a new paragraph
    three or more items separated by commas a bulleted list
    “first… then… after that” a numbered list of steps
    two or three things compared by attributes a table: things in rows, attributes in columns
    “if…, then…” more than twice an “If… — Do” table
    the paragraph’s topic changes halfway a subheading before the new topic
    a command, a path or a piece of config inside a sentence a code block on its own line
    “important”, “note that” one warning per page, the rest as plain text

    Where not to cut

    Case Why
    an argument with “because”, “so”, “but then” the connectors are the content; in bullets they vanish
    a cause next to its effect “ufw doesn’t close a container’s port” without “because the packet goes to forward” is a baffling rule
    a warning next to the step it belongs to a warning moved to the end gets read after things are broken
    a one-item list that’s a sentence; the bullet is superfluous
    a caveat or limit: a version, “not tested on ARM” chunking cuts it first, and without it the text can’t be trusted

    If it doesn’t work

    A 15-item list gets scrolled past unread

    Cause
    A long uniform list gives nothing to hold on to: the items blur together, and the difference between them doesn’t show.
    Fix
    Group them by 3–7 under subheadings, or turn them into a table with an attribute column.

    The list items are three sentences each, and it’s heavier than paragraphs

    Cause
    A list was chosen for looks, but inside there’s argument: a bullet promises a short line and doesn’t deliver.
    Fix
    Argument goes in paragraphs; only enumerations go in a list.

    On a phone a paragraph fills the whole screen

    Cause
    A 6-line paragraph at 714 px is about 13 lines at 360 px: a line holds 35 characters instead of 76.
    Fix
    A paragraph is one thought and up to 3–5 lines on a computer; if it’s longer, look for the second thought.