The README That Made My Coworker Cry (Happy Tears)

Last month, I spent three weeks building what I thought was a brilliant piece of software. When I showed it to my teammate Sarah, she looked at the screen for about 30 seconds and said, "This looks amazing! ...but I have no idea how to use it."

That's when I realized my README file was a disaster. All the information was there, but it was formatted so poorly that nobody could actually follow it.

My Formatting Disaster (A Case Study in What Not To Do)

Here's what my original README looked like:

INSTALLATION
Run npm install then npm start but first make sure you have node 18+ and also install the database dependencies with sudo apt-get install postgresql-dev then create a database called myapp_dev and run the migrations with npx sequelize db:migrate and then...

One giant paragraph. No line breaks. No spacing. Just a wall of text that made people's eyes glaze over.

The actual setup process wasn't that complicated, but my formatting made it look like rocket science.

What Plain Text Formatting Actually Means

I always thought plain text was just... text. No formatting, no styling, just words on a screen. But I was wrong.

Even in plain text, you have:

Line breaks (where text wraps)
Spacing (how much whitespace between elements)
Alignment (where text sits on the line)
Indentation (how far text is pushed in)

These things matter way more than I realized.

The Tools That Saved My Documentation

After Sarah's feedback, I learned about text layout tools that could fix my formatting disasters:

Line Numbers - For Easy Reference

Instead of telling people "look at the part about database setup," I could say "see line 15." Made troubleshooting conversations so much easier.

Before:

Install PostgreSQL
Create database
Run migrations

After:

1. Install PostgreSQL
2. Create database
3. Run migrations

Word Wrap - For Mobile-Friendly Text

My original instructions had lines that went on forever. On mobile, people had to scroll horizontally to read them. Word wrap fixed this by breaking long lines at sensible points.

Text Padding - For Perfect Alignment

This one blew my mind. I was trying to create a simple table in plain text for a terminal application, but everything looked jagged:

Name     Age  City
John     25   NYC
Sarah    30   Los Angeles
Mike     22   Chicago

The padding tool let me set exact column widths so everything lined up perfectly:

Name      Age   City
John      25    NYC
Sarah     30    Los Angeles
Mike      22    Chicago

Much cleaner.

Tabs vs Spaces - The Religious War Resolver

Our team was split between tabs and spaces for code indentation. Some files used tabs, others used spaces, and it looked inconsistent everywhere.

The conversion tools let me standardize everything to spaces (we voted), so now all our code looks uniform across different editors.

The After: A README People Actually Use

Here's how I rewrote that installation section:

## Installation

### Prerequisites
- Node.js 18 or higher
- PostgreSQL

### Setup Steps
1. Install dependencies:
   npm install

2. Set up database:
   sudo apt-get install postgresql-dev
   createdb myapp_dev

3. Run migrations:
   npx sequelize db:migrate

4. Start the app:
   npm start

Same information, but now people can actually follow it.

What I Learned About Plain Text

Formatting isn't about making things fancy - it's about making them usable.

Good plain text formatting:

Breaks information into digestible chunks
Uses consistent spacing and alignment
Makes it easy to reference specific parts
Works well across different devices and contexts

Where This Actually Matters

Code documentation: READMEs, API docs, inline comments

Terminal interfaces: Command-line tools, server logs, system reports

Email: Plain text emails that need to look professional

Data files: CSV exports, configuration files, structured data

Simple reports: When you need something readable but don't need fancy formatting

The 5-Minute Text Layout Check

Now before I share any important plain text document, I do a quick check:

Line length reasonable? Nothing too long for mobile screens
Clear sections? Proper spacing between different parts
Easy to reference? Line numbers if it's something people will discuss
Consistent indentation? Especially important for code and structured data
Proper alignment? Tables and columns line up correctly

Takes 5 minutes, saves hours of confused questions.

The Real Lesson

That tears-of-joy reaction from Sarah taught me something important: Good formatting shows you care about your users.

When you take the time to make your documentation clear and readable, people notice. It's the difference between "here's some information" and "here's information I want you to actually use."

Sarah still brings up that README rewrite in meetings as an example of good documentation. Not because the content was brilliant, but because it was finally readable.

If you're dealing with similar plain text formatting challenges, the text layout tools I mentioned can help make your documentation actually usable.