Neomutt & Bad Documentation

Neomutt exemplifies everything wrong with documentation.

Neomutt advertises itself as an email client for the terminal.

I like email, and I like terminal stuff, because it's easy to automate, and works with all my automation stuff.

That was me, and probably a great many other unsuspecting victims of neomutt.

However, once I opened the man page, I only found out how to colourize my configuration files.

"My fucking what?"

(I cried, in hysterical confusion)

Your configuration. For mutt. Y'know, the configuration file for mutt, which links into the mail-handler on your server? You know the one you've had since '95, when a bulletin board convinced you to change away from notmuch?

No...?

The level of assumed knowledge in neomutt is staggering. And the worst thing about it? It never mentions this. It doesn't state, at the start of the manual, that it's basically just the mutt email client, with some extra colours, and the user must arrive at the hallowed halls of neomutt only after years of deep debate on the fundamentals of the email protocols.

For aeons, Linux users had standards:

1. Download software.
2. Software comes with a manual.
3. Software probably has examples to share, in /usr/share/.
4. You read the manual.
5. You copy an example config from the options.

So it has been among our people, since the beginning of time.¹ Neomutt, however, sits in stark violation of this tradition, as that entire journey sends the newcomer on a grand fool's errand.

The very worse part of this fiasco is that it never mentions what the software takes as assumed knowledge, which resulted in me wasting an afternoon trying to set it up.

Luckily, aerc came out, which does not assume much more than 'uses i3 and likes terminals', which is a perfectly sane thing to assume.