zeal desperately needs some love (and new UI features)

dcunited001 commented 3 years ago

this app is awesome (i have no clue why documentation browsers aren't more of a thing). it saves me so much time. i use multiple editors -- VS Code and Emacs -- and i'm working from fairly recent Linux installations, so autocompletion, doc access and navigate to definition only occasionally work and i can't count on them being available. my current development environment is a work in progress.

however Zeal desperately needs some new UI and other features; see below. I would consider contributing to this project, but there's a backlog on pullreqs and I think more collaboration is needed with Dash developers (why is Dash proprietary?! arggg!)

hide docsets and temporarily delist from search
favorites/bookmarks
integration of swagger/openAPI documentation
discovery for documentation repositories (these are all HTML with no javascript, right?)
documentation on generating docsets
documentation on converting from other docsets (e.g. man pages, doxygen, etc)
declarative configuration (and/or the ability to open XDG config files from the app)
portable configuration (easy to import from a new install)
a few more configurations (e.g. hotkeys)
support multiple versions of documentation
diff the HTML for Dash docsets or intelligently diff the API changes ... which can be done via the dash repo, i guess
better search
perhaps some social features (like medium comments or a feature to help indicate regions of docsets which need user contributions)
save documentation session (for window(s) or a tabset)
multiple windows

it basically needs to be a thin browser that can be addressed/handled as an application by the OS (so i can wire up hotkeys and easily toggle to the docs for reference). for me, the main value here is that all my docs are in one place (& indexed/searchable).

and what the hell is Algolia documentation search, why don't they have GUI apps and why the hell are they proprietary.

sidenote on UI/UX design philosophy

when UI/UX features are not non-deterministically available -- like inconsistent docs/autocompletion availability in UX or pausing to visually ingest the mostly random arrangement of apps -- this implies conditioning to muscle memory will not occur and implies that processes which involve these apps/features/hotkeys require thread-blocking thought that disrupt your ability to focus on the task at hand...
by non-determinism, i mean that one can't deterministically count on pressing a button and getting what i want which means i can't make guarantees about whether i will quickly find information without looking for it. Zeal simplifies this. determinism is important for documentation systems, code editors and OS app management because it implies one action always gets one result and thus: you don't have to slow down and think about it.
the notion that the browser is a one-tool-fits-all-tasks is a plague on productivity for all kinds of users -- esp. without features like search for tabs, webapps that can be treated as apps by the OS. an app like zeal is like my documentation-place and i don't have to go through Google or spend nearly any time finding what I want. Trying to program should not feel like the Truth and Advertising episode of southpark.

tacocats commented 3 years ago

While I agree zeal has a lot of enhancements that can be added, it's also in a pretty usable state. The current maintainer has done an amazing job along with contributors, but I don't think there's a massive amount of people actually contributing to this project. Dash docs only has 1 developer who was kind enough to give permission to this project and other similar projects to use the data that dash uses along with explanations on the formats. I'm sure they would be happy to explain or clear anything up, but most of the features you request can be implemented if there was someone willing to bother adding it to zeal.

Really the main issue I think is this project just needs more contributors. Zeal is written in C++/QT and targets multiplatforms, making it something not many can easily contribute to. Anything that can lower this barrier of entry would help the project such as more documentation on contribution guidelines, etc.