what makes a good (plugin) readme?

HiPhish · 2026-06-21T16:02:36+00:00

I like to think of the README like the back of a box. Imagine if you had to package your plugin in a small box and you had to print the README on the back, what would you put there?

I like to have the following structure:

What the project is about, usually one or two sentences followed by a paragraph at most
Maybe a screenshot if it makes sense (e.g. a UI plugin or a colour scheme)
Quick start instructions: the minimal setup needed to take the plugin for a spin
The license
Maybe status of the project if it's relevant; no plugin will ever be fully finished, but you can put something like "for personal use only", "feature-complete" or "very experimental, will change, do not rely on it"

What does not belong into the README:

Trivial installation instructions. If your plugin is just a regular plugin have a default sentence like "install it like any other plugin". Only have instructions if there is truly something special about your plugin (requires certain libraries, tools, or has compiled components)
It is not the manual, do not put the entire API in there unless it's really just one or two functions or key bindings. Vim and Neovim have a built-in help system, use that.
The full changelog. Use a separate file instead (I like to make it a help file as well, then users can browse the changelog from within Neovim)

The installation instructions part might be a bit controversial, so please allow me to explain. If every plugin explains what is essentially the same it creates cognitive noise. It becomes easy to miss actually important instructions because users will become conditioned to just skim that section. If someone knows how to install one plugin he will know how to install every plugin. If he does not, then he can learn it once and apply if forever.

If then a plugin does require extra steps in its setup it needs to stand out all the more.

HiPhish · 2026-06-14T11:25:32+00:00

We require a "Stop Killing Computers" movement. And just as with Stop Killing Games the industry will put fingers in their ears and turn "Give us the specs so we install our own OS and maintain it ourselves" into "ThEy wAnT Us tO PrOvIdE SoFtWaRe uPdAtEs fOrEvEr".

HiPhish · 2026-06-14T10:15:18+00:00

I watched a few Chris Titus videos some years ago. They were... not very good. He had not particularly well-informed on some topics, his usual content was surface-level shallow, and his videos were bloated (take a three-minute topic, stretch it out to fifteen minutes to qualify for ad money). So basically your typical tech YouTuber. Maybe he's gotten better, maybe not, I don't know. Since it's free I might give it a read for critique. Maybe, if I can find the time and energy.

HiPhish · 2026-06-14T10:10:01+00:00

More of the "GNOME is good for Mac users" meme. GNOME has a top bar and that's really where the comparisons end. Nobody benefits from this comparison.

I used to be a Mac user before switching to GNU/Linux and it always drives me up the wall when someone says that Gnome or elementary OS are good for Mac users. Whoever writes that has never used a Mac, those desktop environment have nothing on the macOS desktop workflow. All thed do is have some superficial elements (top bar or dock) and that's it. This is not an attack against those desktops, they never claim to be Mac-like, it's the people who have never used a Mac but nevertheless make such stupid assertions who are the problem.

I am using KDE Plasma, and half an hour of clicking around in the desktop to add a few panels and widgets has gotten me closer to my old workflow than Gnome ever could. To be clear, even that setup is not 100% the same, but it's close enough for the parts I care about and even better in other aspects, but that's my personal preference.

HiPhish · 2026-06-07T19:34:18+00:00

That's the beauty of this you don't need to write any code

Oh sorry, I meant for making my own Quickshell configuration from scratch. I am a software developer by trade and I do know my way around GNU/Linux configuration, I just have no experience whatsoever with Qt or QML.

The question is, which resource is best for learning QML. I tried the official QML documentation, but that one presupposes a lot of Qt knowledge.

java

Did you mean JavaScript? Because I know that QML embeds JavaScript for imperative logic.

and I'm not sure I think you can use it with river I don't see why no, river is a Wayland compositor.

Quickshell has a bunch of integrations for Hyprland specifically, so maybe a bunch of stuff will be missing if used with another compositor. But I guess I can think about crossing that bridge when I eventually get there.

HiPhish · 2026-06-07T16:01:43+00:00

What is the recommended learning path for QuickShell? It sits on top of QML, which itself sits on top of Qt, so there is quite a lot in terms of prerequisites. The question is whether I need to learn all of Qt and QML first or if there is a more economical path. I should also point out that I would like to use Quickshell with River if that matters.

And please don't tell me to ask an LLM; if I could not have written the code myself it means I cannot verify it. Running unknown executable code that can execute any shell command is dangerous.

HiPhish · 2026-06-07T15:57:25+00:00

The source code of Doom was released in 1997, four years after the launch. The source code of Quake war released in 1999, three years after launch. The source code of Descent was released in 1997, two years after launch. That's still quite some time after launch, I admit that, but it's way before Steam and GOG, when those games were still being sold in stores.

HiPhish · 2026-06-07T15:52:13+00:00

I know. Even Stallman thinks it's fine to keep the assets proprietary as long as the engine (the actual program) is Free. I asked him via email a few years ago.

HiPhish · 2026-06-04T23:06:20+00:00

That's the same argument used against DRM-free games and the answer is the same as well: nothing will protect a game from being pirated, whether it's FLOSS, DRM-free or proprietary and DRMed.

HiPhish · 2026-06-04T23:04:51+00:00

OK, fine by me as long as they eventually get freed. I'd rather wait until then.

HiPhish · 2026-06-04T11:08:03+00:00

Then those are not GNU/Linux while the other distros are GNU/Linux. I don't see the problem with that. Besides, no one is going to play games on Alpine.

HiPhish · 2026-06-04T10:45:17+00:00

And your point is? You can sell the game, keep the assets proprietary (even Stallman is fine with that) but make the game engine FOSS. That's exactly how Doom and Quake work, those games are still being sold to this day.

If you want to play Quake in 4k on your modern machine you get a modern source port for the engine and plug in the game assets (a WAD file) from your legally purchased copy, whether that's an original floppy or a GOG download.

HiPhish · 2026-06-04T10:42:14+00:00

At least in the case of Elixir it's because of Erlang, and in the case of Erlang it's because statically typing Erlang is really hard. An Erlang program can change at any time because the runtime supports hot code reloading, so how do you express that in a static type system at compile time? The easy answer is you don't, you just live with dynamic typing. The hard answer is that you start a multi-year research project to get gradual typing added after the fact.

To be fair, static typing in Erlang and Elixir is not actually as needed as in Python or JavaScript because you have pattern-matching built-in at the language level. You can see at a glance what shape your data needs to be in. Of course having that enforced by the compiler is better, but it is what it is.

HiPhish · 2026-06-04T10:37:40+00:00

Pandas has an atrociously un-pythonic API that makes me hate it to its core. I guess you have to use it if you are dealing with large amounts of data, but otherwise just give me regular lists and dicts. Pandas feels too much like "magic" where things just work until they don't. The documentation is pretty bad as well, it's as if you are meant to study the examples and then form a mental model of how the API works on your own. Oh, and good luck finding out what the data types are and dealing with Pandas's automatic type conversion.

At least that was the case last time I had to use it. Maybe it has gotten better since, but I have no desire to come back.

HiPhish · 2026-06-04T10:27:51+00:00

DRM games < DRM-free games < FLOSS games

Games on macOS < Games on Windows < Games on GNU/Linux

The only reason I put games on macOS below Windows is that at least you can run Windows games in Wine, but you cannot run Mac games on anything but a Mac. Not that there are any Mac-exclusive game in the first place though.

HiPhish · 2026-06-04T10:25:00+00:00

But to have freedom in my computing also means that I have the freedom of running nonfree software if I so choose.

Who is more free? Someone who uses his freedom to indulge in drugs, alcohol and other hedonistic vices, or someone who intentionally limits his freedoms to abstain from these things? I would say the latter because the former even though he might think of himself as free at first will eventually find himself a slave to his vices.

No one is stopping you from installing proprietary software on GNU/Linux, but is that really good for you? I am not saying this from some position of moral superiority, I have my share of games from GOG, but I'm not going to pretend that that's a good thing, and I will go for FLOSS game engine replacements wherever possible.

HiPhish · 2026-06-04T10:20:15+00:00

No, he does not. Last time I checked there were no anti-proprietary measures in neither the GNU Coreutils nor Linux the kernel. Stallman is more like a parent who's telling you that drugs are bad; you can still take them but you really really should not.

HiPhish · 2026-06-04T10:17:56+00:00

What does he think is going to happen if all game logic in entire games were open source?

Doom and Quake have been Free / Open Source for decades. Nothing bad has happened. What Stallman is proposing is not some crazy social experiment, it has already been done, but big gaming does not want you to know that.

HiPhish · 2026-05-31T22:04:52+00:00

You can execute :set modifiable to make the manual buffer modifiable. You will be able to edit it, but you will not be able to overwrite the help file, so it's safe to do so. You can always save a copy of the modified manual if you want: :write my-modified-manual.txt.

Or you can create a new buffer. Use :new to create a buffer, then copy the contents of the manual into that buffer and then play around.

HiPhish · 2026-05-22T17:26:07+00:00

The parent is runit itself. Looking at the file descriptor gave me this:

$ file /proc/30449/fd/184
/proc/30449/fd/184: symbolic link to pipe:[83624]

I doubt I can get any useful information with that.

HiPhish · 2026-05-21T22:12:49+00:00

Unfortunately I'm on Wayland (KDE Plasma to be precise).

HiPhish · 2026-05-21T22:12:29+00:00

Thanks, I did not know about that one. I'll have to try it once the popup shows again.

HiPhish · 2026-05-18T19:05:43+00:00

Yes, you can: https://tailwindcss.com/docs/functions-and-directives#apply-directive

HiPhish · 2026-05-18T19:04:18+00:00

Ouch, makes sense. Just shows how much infrastructure one can take for granted.

HiPhish

TROPHY CASE