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.
> 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.
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.
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
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 ;)
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.
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.
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.
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.
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.
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.
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.
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.
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?
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.
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
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.
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.
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.
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...
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.
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'.
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.)