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.)
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.
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'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.
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
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.
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 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 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.
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?
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.
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.
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.
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?
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 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.
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.
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!
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.
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.
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.
Readit News
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.)
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.
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.
* https://writethedocs.slack.com/archives/C6D77HJ4F/p168556139...
* https://www.reddit.com/r/technicalwriting/comments/13wvmbt
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.
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 recently discovered devdocs.io and the emacs integration[1] and like it so far.
[1] https://github.com/astoff/devdocs.el
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.
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?
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.
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.
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.
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
Also, even with high speed internet, it is several seconds at least, while zeal/dash will return it basically instantly.
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.
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.
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.
A more limited and focused selection of documentation gets me exactly what I need. It's also a lot faster then documentation websites.
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.
You don’t need to build it yourself, there is a brew formula.