Our README is thorough and nobody reads it. Why

Back to list2025-07-25
You

Our README is thorough and nobody reads it. Why?

ChatGPT

Because it answers questions in the author's order, not the reader's. Lead with what the thing does in one sentence, then how to run it, then the caveats. Anything a reader cannot act on in the first screen is reference material and belongs further down.

You

What belongs in a changelog entry?

ChatGPT

What changed for the user and what they have to do about it. Internal refactors do not belong unless they change behaviour, and "various bug fixes" is a line that costs attention while carrying nothing.

You

How do you shorten a document that feels bloated?

ChatGPT

Delete every sentence that restates the previous one, then every adjective that would survive being wrong. What remains is usually 60% of the length and all of the meaning. If a paragraph resists, it is doing two jobs and wants splitting rather than trimming.