[Suggestion] - Improve onboarding & out-of-the-box experience for dotfiles #3
Description
Improve onboarding and out-of-the-box experience for new users
Trying these dotfiles on a clean Linux install is harder than it needs to be.
A lot of important things currently happen “off-scene”:
- Required packages (
apt,pacman,yay, etc.) are assumed to already exist - Setup varies depending on distro and window manager
- Some configs (
zsh,p10k,tmux,nvim) may be overridden without warning - New users don’t know what gets installed, what gets replaced, or how to use the setup once it’s running
This makes testing or experimenting risky, especially for people spinning up clean machines or trying dotfiles for the first time.
What would significantly improve the experience
Explicit dependency handling per distro
Having clear install scripts or documentation per distro would help a lot, for example:
- Arch (pacman + yay)
- Debian / Ubuntu (apt)
- Optional: Fedora
Even simple scripts that list required packages and fail early if something is missing would remove a lot of guesswork.
Window manager clarity
Setup differs depending on the window manager (sway, etc.), but this isn’t obvious up front.
Either:
- Clearly document which window managers are supported
or:
- Provide simple WM profiles (e.g.
sway,minimal, etc.)
That way users know exactly what they’re installing.
Safe install with automatic backups
Many users already have existing configs:
- zsh
- p10k
- tmux
- nvim
Overwriting these silently is risky.
A pre-install backup step that:
- detects existing configs
- backs them up with a timestamp
- prints what will be changed
would make trying the dotfiles safe and reversible.
Beginner-friendly “how to use this” section
After install, new users still don’t know how to actually use the setup.
A README section with:
- the most important keybindings (nvim, tmux, rofi, yazi, lazygit)
- how to open the launcher
- how to switch panes / windows
- how to exit safely
would massively lower the entry barrier.
Optional one-shot install
Optional, but very powerful: a single install script that:
- detects distro
- installs dependencies
- backs up existing configs
- installs dotfiles
- prints post-install usage hints
Advanced users can still do everything manually.
Why this matters
These dotfiles are solid and actively maintained. Improving onboarding would:
- make them approachable for beginners
- make experimentation safer for experienced users
- reduce setup friction and abandoned installs
- turn this into a reference-quality dotfiles repo
If useful, I’m happy to help with install scripts, backup logic, or README improvements.