Home

🔍🐟 fzf.fish wiki ✏️📘

Welcome to the Wiki, where you can read the Q&A style help or learn about the vision of this project!

Bear in mind that while I update the Wiki in lockstep with the main branch, I do not keep around documentation pertaining only to previous versions. Therefore, consider updating fzf.fish before reading the Wiki.

Why are new issues, pull requests, and discussions disabled?

First off, fzf.fish is not abandoned. The truth is I am burnt out. I love adding new features, but responding to the messages I get has been draining. Sometimes it's helping users debug issues that often turn out to be user error. Sometimes it's heart-wrenchingly declining a PR someone put a lot of work into but is unfortunately a bad fit. Frequently its saying no to requests for new features that I simply have no interest in or would be a bad fit. Rarely, thankfully--but it has happened--it's defending my product or design decisions from detractors.

I have become demotivated to add new features because I dread the deluge of messages that come after. Of course, sometimes I get helpful messages, but the balance is heavily shifted in the unhelpful direction. My first attempt to mitigate this was investing in this Wiki (especially the Troubleshooting guide) and using templates to link to the Wiki and encourage users to search previous issues and questions. That proved insufficient. Next, I considered disabling notifications and not checking fzf.fish but it's hard not to. Plus, it's rude to make those who post messages wait indefinitely for a reply.

So instead, this is my new plan to balance feedback with my own energy levels:

• By default, interactions are disabled with the repository.
• When I add new features, I will re-enable interactions for a time to gather feedback and bug reports for a few weeks. In this short period, I can be fully available and reply to issues.
• Once I believe fzf.fish is stable again, I will disable it.
• I will occasionally pull for feedback from trusted collaborators.
• Users who need help with existing features can unblock themselves by searching the Wiki and existing issues and discussions.

I expect this change to make working on fzf.fish more enjoyable for me and give me more space to thoughtfully guide its evolution. And hopefully in the long run, this will better for everyone.

Why does documentation live on the Wiki instead of the readme?

Much of the content of the Wiki originally lived in the readme. Initially, it made sense to consolidate all the documentation on the readme as the readme is easily accessible and can be updated alongside the code. However, this became burdensome and counterproductive as the plugin grew:

• There is a tension between providing comprehensive documentation and keeping the readme easy to scroll through. It requires a lot of effort to balance that.
• No matter how succinct I tried to be, the readme was becoming very long, such that it was intimidating for prospective users and hard to navigate for existing users.
• People reading the git log for the latest changes likely find non-feature-related diffs and commits changes distracting.
• Making updates to the front page of the repo is anxiety-ridden for me, but updating Wiki much less so.
• Having multiple pages and a sidebar at my disposal makes organizing the content easier.
• Much of what I wanted to explain to users is not documentation per se (e.g. FAQ and design philosophy).
• Finally, I obsess over my words and find myself writing and rewriting every sentence again and again.