Zeal is an offline documentation browser for software developers | Hacker News Reader

Zeal is an offline documentation browser for software developers

zealdocs.org

348 pointsdistcs108 comments

I wish this approach were more supported by those producing documentation. Looking things up in reference docs is one of those cases where reducing friction yields huge productivity benefits, but I still end up using a search engine (Kagi now as Google hides authoritative reference docs under a pile of poor-quality, irrelevant spam these days). I've tried Zeal multiple times but while the app is nice and many of the docsets are good, many of them aren't good: badly formatted, badly indexed, outdated or simply nonexistent. A search engine requires no setup and covers everything. It's just so horribly slow.

If we were grown ups, all software authors/vendors would be providing their reference docs in a standardised form, findable, downloadable and displayable by a wide range of tooling, consistent across languages, IDEs and platforms. Zeal is the closest we have, and it's a noble effort, but IME it doesn't solve the problem well enough to be useful because there's no buy-in from the people producing the docs.

(First to mention ChatGPT gets slapped with a wet fish. Just try me.)

In hope I avoid getting slapped with a wet fish, I would love to see a future version of Zeal with an option to ingest the docsets into a vector database and "chat" with it using a (local) LLM that's fine tuned for answering technical docs questions.

To stay on topic, I feel the pain: Zeal is so nice I curse when I need to look up something in the docs that aren't supported (Django REST Framework, in my case), since they use a different doc framework and can't be easily prepared for Dash/Zeal.

Somewhat related: wonder if using a local LLM could make it more feasible to federate reference documentation by translating various doc formats into a common one.

And on the other side of things, there's a growing trend in the Python library ecosystem of simply not writing reference documentation at all, instead providing either a few or a lot of user guides and tutorials, and directing users to either read those and try to interpret their mysteries, or expecting users to read the source code and interpret those mysteries. It makes no sense to me. The Pydantic issue tracker for example is absolutely full of people simply trying to figure out how to use the damn thing.

Glad you picked on pydantic. There is no reference doc whatsoever. The expectation is that you are supposed to learn by reading examples!

Back in the days of yore, software engineering teams led by greybeards used to be conservative in what dependencies they import into the projects. Those days are gone! Everyone imports everything today without any discerning eye.

> Those days are gone! Everyone imports everything today without any discerning eye.

That's even considered a feature today! If you don't have a language package manager that allows you to transparently import tons of stuff you've never heard of, then the language is considered crap.

Even the good old venerable Ada language (or rather: its most visible vendor) jumped on that bandwagon with https://alire.ada.dev/ :-(

Yeah, I was struggling with this trend earlier when looking at the Textual library, which has amazing examples but doesn't seem to have very detailed full API documentation.

I wonder why this trend is happening, especially when python in particular has a bunch of standards and tools to make generating full API docs pretty straightforward.

I think it's partly because Sphinx is clunky and people have been using MkDocs instead, which I believe either doesn't generate anything from docstrings at all, or didn't until recently. I don't know why they're not using Pdoc, maybe they don't know about it.

I also get the sense that there is a growing movement among programmers that API reference documentation is useless, or not worth putting effort into, because it's possible to go out of sync with the code and "nobody reads that anyway". I've heard people say things like "if you're advanced enough to read reference documentation, you're better off just reading the source anyway." It seems to be rooted in some kind of combination of extreme cynicism, a distorted sense of how people who aren't raw beginners learn to do things, and of a kind of false minimalism, wherein API documentation is old fuddy-duddy stuff for Java and C++ developers, and the new friendly easy way is to just read the examples. Such libraries also seem to exhibit a poor separation of public and private interfaces, so maybe it's just a reflection of people being bad at designing libraries.

Unfriendly and short-sighted (at least if you want your lib to be used, else why publish it?), is more like it.

But they spent hours writing all those examples. I think it's the opposite, it's a misguided attempt at being friendly. Short-sighted, I agree with.

Okay, I get you, and agree. Yes, friendly, but without thinking, at least some, at a higher level, what might be a better use of their (limited) time.

I think what you've said feels exactly right. Maybe a better Sphinx just needs to exist, it seems like pythons standards should make it pretty simple to write something where API documentation generation is so trivial there's no reason not to.

I normally do end up reading source code, but it often introduces unnecessary hassle because while it's great for "what does this function do?" type of stuff, it really falls down when you want to know "what type of functions fall under this module" since you end up navigating up and down through a lot of imports that make sense for code organization but are abstracted away at the point of use.

You can use the mkdocstrings plugin with mkdocs which will generate api docs from your functions and classes and their docstrings just like Sphinx does. It even supports inv files just like Sphinx so you can reference third party libraries in your own reference docs

https://www.kiwix.org/en/ Has some nice stuff for offline, but it’s not really optimized for it.

I miss the documentation that was part of Microsoft MSDN subscription. I now work in a sandboxed environment and cannot access help for the APIs from within that environment so something that I can download in it's entirety and get into that environment would be ideal.

I'm a technical writer. I have felt this a lot myself. It is very comforting to know that the man pages are always there if I need them. Same with the Rust docs. And Beej's Guide to C Programming (I downloaded the PDF). Conversely, it kinda sucks to have to rely on a website to get info. I will kick off a discussion around offline docs in the technical writer communities that I'm part of.

* https://technicalwriting.tools/posts/offline-docs/

* https://writethedocs.slack.com/archives/C6D77HJ4F/p168556139...

* https://www.reddit.com/r/technicalwriting/comments/13wvmbt

rust docs is one of the reasons it's the so nice to use. Javadocs are nice but so many libraries have their own format. Everyone using the same thing makes it so much better

Does IME == In My Experience ?

It does.

Yes. Apologies. I'm used to using that in chat with people familiar with it, but shouldn't have here. Random unexplained acronyms are annoying.

I’m a happy user of Dash (macOS) for years now. Sadly Zeal is not 100% the same in terms of integration etc. at least I never got it running on windows and Linux like on Mac. I only use hot key setup (alt-space in my case) No fancy ide hot keys and such.

There used to be some controversy (around 2015) when the author (single dev) put out yet another breaking version with new license upgrades. The free version was artificially slowed down. He added a new search backend and wanted to be compensated. So all users had to pay again. I upgraded 3 or 4 times. I think it’s a great tool that solves a problem. Some feel that he only wrote a parser/display tool and that the price is too high. I wished I came up with the idea though ;)

I didn't know zeal was being updated at all since the last "release" is almost 5 years old.

I recently discovered devdocs.io and the emacs integration[1] and like it so far.

[1] https://github.com/astoff/devdocs.el

Couldn’t one use Obsidian to do the same task? It sounds like it could.

The point of Zeal is downloadable docsets for offline usage (cppreference, MDN, GNOME docs, etc.), whereas Obsidian is more of a personal wiki you fill yourself AFAIU.

You could clone the doc repos and just open with Obsidian to get nice rendering.

I use cheddar for this, it’s so versatile

Do you have a link? Never heard of cheddar.

I think skrebbel was parodying prox's reply as a commentary on drive-by comments about a seemingly orthogonal technology.

I actually don’t follow the releases just know that it is the variant for windows and Linux.

I have Zeal installed on my Linux desktop but I rarely use it.

The reason is that most of the time, I want to read documentation for a specific version of whatever thing I'm using. Zeal only has docs for the latest version, or in some cases, major versions. Take Ansible and Python, for example. These tend to have breaking changes, new features, and hard deprecations in their minor version releases. So knowing that I'm looking at the docs for Python 3.8 vs 3.11 can be very important.

One of my "someday" projects is to write a doc viewer with an obnoxious plethora of sources including docs shipped for every minor version of a program, docs for operating systems, man pages, info pages, maybe even wiki content for exceptional wikis like arch and gentoo.

The opposite is also true: the JavaScript AWS SDK on Zeal is v2 and the bleeding edge is v3.

I've seen this in a lot of offline/fast/??? focused documentation systems... and I really don't get it. Version matters a lot to developers. Wouldn't the developers know this... being developers themselves?

But then I see similar things in supposedly mature and even-more sophisticated systems, like mypy's typeshed which only supports a single version of external libraries' type declarations.

How? What madness leads to this? Why not support multiple versions, and offer a way to select them per project from standard dependency declarations, so you're always reading the correct version?

Does the Python documentation not meticulously list the entire history of changes at method level?

Or use devdocs.io on the web. It works well offline.

https://devdocs.io/ absolute recommendation

I wish it had a proper installable app. Relying on browser local storage is a nightmare since your browser will randomly and with no warning delete it all. The whole point of offline docs is that they're available... offline. On more than one occasion I've gone back to devdocs.io and everything I saved locally is wiped out, and of course I'm offline and just can't do anything.

Give me local HTML files I can stash in my filesystem. I actually just use wget to recursively archive entire documentation sites to local folders and serve them up with python's built in web browser. It's the only way to be sure I have accurate and up to date offline docs.

Give me local HTML files I can stash in my filesystem.

Apparently devdocs does have an API to download docsets. I just installed the Emacs package that someone recommended in another thread and it let me download the docs.

which package please?

Sign me onto this same worry. It only takes one incident of offline mode borking to get upset.

Since the devdocs representation is so standardized, I have wondered if I could dump their database into SQLite and browse it with datasette. Should even be able to maintain text searching.

Could you elaborate ? What is datasette ?

Is the Zeal code open source enough that one could change the backend by replacing a small number of data access subroutines?

I think all you would need to change is setter code, since getter code wouldn’t be part of the interface. I think Zeal doesn’t write back any data, right ?

Not experienced with Zeal, but I have used devdocs, which is open source. Devdocs parses the relevant documentation pages and stores them in a more structured way inside a browser database file. I would prefer to keep that in a local SQLite file I fully control. However, storing the data is not enough, I need an easy way to search and browse the documentation. Datasette is a Python project which spawns a web interface to a SQLite database which gives an interactive way to explore the data. This interface should be sufficient for locally hosting and searching the documentation.

>your browser will randomly and with no warning delete it all

With Chrome based browsers this seems to happen usually on browser restarts after version upgrades, however With Firefox I have never had such issue

There seems to be an Electron Desktop client: https://github.com/gengjiawen/electron-devdocs

I use this (https://github.com/astoff/devdocs.el) emacs package to download devdocs locally and access them from emacs, which is pretty great.

Is there no browser plugin that can give a more reliable offline browsing experience than browser cache and more convenient than wget?

I love devdocs.io when it works, but almost every other time I open it, it has forgotten my documentation configuration and I have to start from scratch. I don't have problems losing cookies, etc., elsewhere. And I have a peeve with it asking me to reload the page over and over and over, and each time I do it loses my place. It's a great source otherwise.

Looks great. Related product for comparison: Dash https://kapeli.com/dash

I loved Dash when using a mac. But I've been full time in linux for the last 6 years and Zeal is the only thing _close_.

I've tried to use an offline documentation browser a few times before (Dash on Mac) but have never really been able to get into the habit of using it. I generally just end up Googling for what I'm looking for. Outside of low-connectivity situations, what benefits do people find with these viewers?

Speed and snappiness mainly. Skips at least two slow page loads (Google and the docs page).

But yeah, it took me a while to get into the habit as well, and the benefit was pretty small. It mainly just feels nice.

Exceptionally quick lookups: alt + space and Dash is there with the search focused. I search and press alt + tab or esc to get back into my editor.

Honestly: that it's not Google.

A more limited and focused selection of documentation gets me exactly what I need. It's also a lot faster then documentation websites.

I actually only started using Zeal during the last few months...but similar to you, the trap i fall into is that muscle memory has not been built up with me to *remember* to check zeal before resorting to a search engine. However, those few times that i *did* remember to use zeal, for me it was really great, solid experience!

For me, the combination of Dash and Alfred is the productivity boost. Alfred makes it very easy to search documentation in Dash. You can have unique keywords in Alfred to target specific packages in Dash. For example, “guava: ImmutableList” or “sidekiq: Client”. I find it especially useful with Dash on a secondary monitor while the editor is on the primary so that both are visible at the same time.

What's the difference between using Alfred to search vs using the hotkey to open a Dash window in search mode?

I don’t think there really is a significant difference, unless you’re already using Alfred. I’m an Alfred user and it’s kind of the “start everything place” window for me, the system-wide equivalent of a text editor’s command palette, a CLI for the GUI.

Agreed. I just tried out the Dash hot key and it’s basically the same. I’m tempted to claim the Alfred integration is better but that’s probably just me being a user of Alfred.

I have felt the same way, and curious to what others say about it. I assume the problem I have is that I am not always good at asking the questions of the documentation that I mean, and Google is good at inferring my meaning. More often than not, I don't just need the method signature, but some narrative around what and why. But I try things like Dash again when they come up, or moments like this. To your question, offline browsing is the biggest benefit I see. Long plane ride ahead, or cruise, or train ride? Take your doc with you.

> what benefits do people find with these viewers?

I stop and think about the issue instead of just googling for an answer.

Also, I removed the wifi card from my laptop so I can work from a room without ethernet letting myself get distracted by the internet.

Google has become a terrible search engine to the point that the first mention of the official documentation will be half a page down with some random version. I have to enter like 3 queries for the most trivial workflow of displaying the official documentation’s relevant pages.

Also, even with high speed internet, it is several seconds at least, while zeal/dash will return it basically instantly.

For many queries, Google offers more of a "ready-made" solution e.g. from a StackOverflow post or blog.

When looking at the offline documentation, I know that I am looking at a supported version (not something ancient or much newer than what is deployed in production) and that I am looking at the "authorative" answer i.e. the "real" docs not some third party comments.

When the program I am developing is expected to run correctly even in the presence of errors, it makes a lot of sense to me to consult the authorative documentation rather than "the web" which rarely covers all of the possible corner cases.

A program on the bus without internet access so this is just perfect. I often download whole websites for this reason or bit better you can print pages off as PDF documents.

Maybe I'm blind - but i can't seem to figure out a) what you get when you pay for Dash on Mac vs download? Or b) why i can't use zeal on Mac?

Dash is a commercial software on macOS. The author created the whole docset parsing/plugin stuff and markets the tool. I use it for years and upgraded multiple times since it’s a timesaver.

There has been controversy in the past about the tool since it is a glorified man page reader. The author even shared at one point his earnings and what he is doing with it.

And no there is no zeal for macOS. I don’t know the details behind that deal. I can only say that zeal is not as good as dash. The integration into macOS is way smoother than what one gets on windows and Linux. I tried all versions.

IIRC, Zeal and Dash have a deal with eachother - since Dash has no plans for non-mac devices, Dash told zeal the docsets can be used free of charge as long as zeal does not provide release builds on Mac. I believe you can build zeal on mac on your own.

Here is the github discussion created by dash author explaining the deal https://github.com/zealdocs/zeal/issues/24#issue-17915169

It’s not widely advertised (probably this is the deal) but Zeal works fine on macOS, see this: https://github.com/zealdocs/zeal/wiki/Build-Instructions-for...

You don’t need to build it yourself, there is a brew formula.

I wish I could use Zeal to browse the Apple documentation as well, but unfortunately that’s exclusive to Dash.

I’ve even paid for Dash to get that feature, but no longer use it due to some UI changes in the latest version that add extra clicks for each search query, making the UI inefficient.

Zeal seems to have be inspired by the old and efficient Dash UI, but I can’t have both that and the Apple docs from what I can tell.

What was the feedback from the author when you told her that the extra clicks made it unusable ?

The communication with the author (Bogdan) has unfortunately been lacking, taking very long to reply (months) and at best confirming the issues but without any plans to fix them.

See https://news.ycombinator.com/item?id=25434191 for prior discussion about my experience.

Nice. The dependency of Qt WebEngine (i.e. Chromium) is a bit unfortunate (size, complexity); sure QTextDocument/QTextLayout/QTextHtmlParser/QCssParser is not sufficient enough for this?

Agree, qt5-webkit takes ages to build on my machine

The Norton Guides were good in their time, too. IIRC, Turbo C, 8086 assembly(?), Clipper, etc. were supported. It was a TSR too, so you could pop it up from any another app by a hotkey.

Wasn't a browser like this integrated in Windows at some point? Just download a bunch of CHM files and you're good to go to the wilderness.

the equivalent on macOS was to use Dictionary, but I suspect that it not really viable anymore due to format/rendering contraints: CHM probably needed IE6 like compatibility, after looking for docs, Dictionary needs XHTML, which might easily cool any enthusiasm

Looks similar to CHM which was my favorite documentation format back when I was using Windows.

I still use dash 4. The newer versions removed the explorer tree and I don’t see any way to get it back. I feel like they make newer, worse versions, for the sake of selling upgrade licenses.

Same here - it's a shame because I'm happy to continue supporting the developer, but I won't pay for a functional downgrade.

Have you tried devdocs?

No, not for any length of time. I prefer having a desktop app, and Dash 4 still works for me, so I have not had a reason to switch... yet.

First posted almost a decade ago: https://news.ycombinator.com/item?id=6171667

What are the advantages over https://devdocs.io/ ?

Wish the site was clearer that Zeal serves ads.

Gross

Removed in the master branch, btw.

Happy user here - Zeal (and Dash on MacOS) is an easy productivity win, even if you're online (Django online docs search is notoriously bad for some reason), and indispensable if on a spotty connection or offline.

Any tips for a dash+alfred alternative on windows?

I didn't try Zeal on Windows, but it's a supported platform, so I would assume you can register a hotkey there as well.

Zeal is great.

I would appreciate it when Devhelp (Gtk) allows the user to install further docs. The requirement to place docs somewhere in “/usr/share” is obvious but doesn’t fit the user needs.

Does /use/local/share work? or ~/.local/share?

I saw this post and thought there was a new update... sadly, this app has been sitting at the same version since I built my PC years ago.

Zeal (portable 64-bit) runs on Wine on macOS if you don't need the Mac-specific stuff in Dash.

Zeal is ideal when you have no connectivity. And when you want low latency and no distractions.

Also, http://devdocs.io, which implements the same functionality and supports offline browsing as well.

And lots and lots of third party docsets: https://zealusercontributions.vercel.app

Thank you for the link. Is there a non-zeal way of creating a docs to processing one ?

Dash, but it's a paid macOS software (which does give a free trial).

I'd be happy to hear of others, but the situation for generating docs is pretty dire right now (as far as I can tell).

It's generally a pretty manual process, as there's no universal mapping from upstream documentation to docsets.

When you're starting with Doxygen documentation: https://github.com/chinmaygarde/doxygen2docset or https://pypi.org/project/doxytag2zealdb. If it's Sphinx-like, then https://github.com/hynek/doc2dash

Otherwise is it probably best to look for a specific tool for the type of docs and then look through the GitHub submissions to the user-generated docset submissions for clues for specific code bases: https://github.com/Kapeli/Dash-User-Contributions/pulls?q=is...

1. Download windows portable

2. Unzip & run

3. Install java 19 doc

4. Search for "List" on top-left search box

5. Wait 1 second

6. Zeal crashes

7. Try navigating, it crashes

I haven't had such a bad first experience in years.

Do you remember Qt Assistant? (Just slap "qt ass" in your type-ahead start menu!) Pepperidge farm remembers.

If only it had Vim keybindings...

For me, the best documentation is often the manpages and perldocs, both of which can be navigated using VIM keybindings.

For the remainder of documentation, I found HTML to be the “best” format and thus view them from the Web Browser even when using offline copies. To make them accessible, I use my browsers home page - a reduced version is shown here: https://masysma.net/32/ial.xhtml - and in the most recent version it supports some rudimentary movements like hjkl...

This software on Windows really is great (as of 1 year ago) specifically the font aliasing and size didn't match the rest of the system. It was way Smaller to the point of being unreadable for me.

I want this for my phone

Offline documentation browser for sad and unlucky developers without internet.

In the old days people had locally installed man pages. Documentation or manuals should be delivered locally by default. It's handy for when you are traveling and have no mobile internet connection, I've been in the alps where there was no network connection at all. It was very good to have everything I want to lookup (wikipedia, devdocs, cached browser history, epubs, stackoverflow) local. I can imagine it's handy to maintain focus as well, no internet distraction. For people who can't affort an network connection it's heaven. Instead of 'sad and unlucky' I'd say 'smart and lucky'.

People are not online all the time? Still manually search through documentation? ChatGPT, make a Haiku about this!

    Offline docs still used

    Death will take care of that soon

    LLMs, the new way

Some of us prefer to read primary sources written by other humans, instead of a hallucinatory regurgitation from a probabilistic token stream model.

Reply on news.ycombinator.com