Remove hard line breaks from READMEs / Marijke Luttekes

When working with accessibility and inclusive design experts, I learned many lessons, one of the most unexpected ones being to avoid hard line breaks in README files.

Why do we use hard line breaks?

The length of a line, or rather the number of characters in it, affects a text's readability, with reported ideals between 40 and 100 characters on a line. (Per my article Technical documentation writing quick tips.)

Programmers have historically chosen to constrain the number of characters on a line, which led us to limits like 80–120 characters of code. Documentation may be capped at shorter lengths, for example, 72 characters per line.

We often introduce hard line breaks to enforce character limits in plain text and similar formats, like Markdown or reStructuredText (RST).

So, why should we remove the breaks?

Let's eliminate hard line breaks in plain text(-like) files, particularly READMEs.

But why, you may ask. The short answer is: inclusive design.

The longer reason is that the chosen line lengths often only work for one screen size and zoom level, particularly for sighted users.

Have you ever tried to view hard-wrapped text zoomed in or on a slightly smaller screen width than it is intended for? If not, try it; it's ugly.

Ugliness aside, your chosen line length may not work for everyone: ideal length and presentation are a preference (don't worry, we won't judge!) or a necessity based on someone's field of view or disability.

Hard line breaks also force screen reader users to navigate from line to line rather than read an entire paragraph directly.

In other words, the line breaks take away a user's agency over how they consume the content, all because of an arbitrary restriction.

Let your editor soft-wrap lines

Now that hard line breaks are out of the way, you may wonder how we can achieve line wrapping without them. The solution is in your IDE's settings.

Take your editor of choice and explore the user preferences. Look for words like "soft", "wrap", "break", and "column" to find relevant settings.

Since VS Code allows separate configurations per language, I set my word wrapping to 120 characters for all files and 72 characters specifically for Markdown. Your experience may be different.

Tips for Visual Studio Code—my current editor of choice—are below.

Configuring VS Code

VS Code gives you many customization options for settings, including overrides per language or scope. Below are the settings I use for wrapping.

Open your user settings as JSON, add the following lines, and tweak them where you like:

{
    "[markdown]": {
        "editor.wordWrapColumn": 72
    },
    "editor.wordWrap": "bounded",
    "editor.wordWrapColumn": 120,
    "editor.wrappingStrategy": "advanced"
}

To explain what is happening here:

We set the word wrap to bounded, which means that lines will wrap at the end of the viewport or the word wrap column length, whichever is smaller.
The wrapping strategy is set to advanced, a slower process but a bit nicer than the default settings (opinion). You can omit this setting if you prefer.
The default wrapping column is 120 characters and set to 72 for Markdown only. Adjust these values to your liking.

You can optionally add rulers as a visual hint for several line lengths. For example:

{
    "editor.rulers": [
        72,
        80,
        100,
        120
    ]
}

Note on rendered documentation

Documentation rendered from Markdown and RST, among others, is simply HTML.

If the rendered HTML does not take hard line breaks from the source code, paragraphs will be read as regular text without the previously described issues.

Wrap-up

Remove hard line breaks in favor of soft ones to give users more agency over the text they read. They can zoom and adjust to their heart's content, and you won't have to manage all those line breaks in code!

Article series