Bspwm is powerful - but it's Documentation is a Mess. So I Built a Wiki.

#linux #opensource #documentation #productivity

When I first started using bspwm, I loved the idea behind it. A minimal window manager, clean design, everything controllable through commands - exactly feels like my home territory in linux, as it uses bash and I love bash.

But learning it? The painful process.

Bspwm has a good community, though small and has sparse documentation. Beginners would have to suffer after encountering errors, because the manpages does not help. It says This is the command and syntax, use it. and does not provide any explanations for why, how or the process behind it's working. Information was everywhere and nowhere at the same time. Some docs here, a man page there, random GitHub gists, old Reddit comments, half-explained examples in dotfiles. Every time I wanted to understand a single bspc query or behaviour, I had to jump between five sources and still guess what was actually happening.

What bothered me most wasn't that documentation didn't exist - it did - but that it wasn't connected, completed, or explained deeply. Most guides assume you already know how bspwm thinks. If you don't, you're stuck copying configs without understanding them and end up breaking your system.

So I started taking notes.

At first, it was just for myself. I wrote down what each bspc query actually does, what the flags mean, what changes when you target nodes versus desktops and what happens internally when a command runs. Over time, those notes turned into something bigger.

That's how bspwm-wiki started.

The goal of this wiki is simple:
not to provide "cool configs", not to rice screenshots, and not to repeat the man page - but to explain bspwm properly.

I focus heavily on the following things. I framed it as a community project. But no one contributed yet and I am the solo maintainer of this project. I can maintain this forever if this is helpful to many people.

how bspc query really works
what each selector targets and why
how bspwm's tree model affects behaviour
explanations in paragraphs, not command dumps or short bullets.

Every page is written as if the reader is learning bspwm for the first time, but still wants the full depth. There happens not shortcuts or magic, but pure understanding.

The wiki lives here:
-> https://rdbhvr-001.github.io/bspwm-wiki

It's still growing, and it's very much a community thing. If you've ever been confused by bspwm's docs, or if you've learned things the hard way and wish someone had explained them earlier - that's exactly who this is for.

Feedback, corrections, and contributors are more than welcome. If something is unclear, incomplete, or wrong, I actually want to know. Good documentation only gets better when more eyes are on it.

Want to contribute?
-> https://github.com/rdbhvr-001/bspwm-wiki

If you're using bspwm and ever felt like "this should be documented better", I probably felt the same way - and tried to write it down.