Since my earliest university days, I’ve spent a lot of time trying to get better at computers, immersing myself in the world of Linux, and generally improving my software development skills.

One of the aspects that was the most helpful to help me grow was attempting to replicate my normal dev workflow, but with less: Learn to operate on Linux not Windows, then learn to do dev via on the terminal instead of GUIs, and eventually learn to do the same but offline, without any network calls.

These self-imposed challenges taught me about tools and resources that I otherwise wouldn’t really have reached for, and I’m a better nerd for it.

Today, I want to share one of the tricks I’ve grown to enjoy: offline documentation. Specifically, I want to discuss Zeal, an offline documentation browser based on the work from Kapeli’s Dash on MacOS. We’ll cover the Zeal tool, the file format, how to find good docsets, and how to generate your own, and sharing them.

The lost art of RTFM

I’m given to understand that nowadays it’s cooler to look up basic documentation via ChatGPT or other language models, asking a chatbot for the answer to questions that the documentation covers.

Before that, some used to reach out on StackOverflow, new questions answered by someone quoting the docs directly. The growing back-catalog of standard questions and answer became its own encyclopaedia of development, so that when searching basic docs questions on our favourite search engine, we find the answer on StackOverflow. Even though, again, this answer is a quote of the docs, most often even still fresh with the docs page link!

I advise everyone I mentor to master the art of ‘Reading The Fine Manual’: becoming the only person in your organisation that actually has read the docs allows you to bypass all the middlemen of Stackoverflow, gaining crucial cycles in a discussion about “can we do this?”, turning doubts into strong answers like “yes, we can, there’s a flag for that, let me find it again”.

In particular, remembering not the whole docs, but what exists, is why I end up re-reading the full Dockerfile specs, and docker-build CLI reference every few months, just to see what I’m missing. Every time I have re-read it, I found a few tricks in there that proved useful within days.

So, get comfortable reading the documentation, whatever it is: specs, RFCs… You’ll get a leg up on people who didn’t, and get inspiration for solving the problems of your day.

But sometimes this background knowledge isn’t enough, you still do need to look up exact syntax etc. This is where our tool of the day comes in.

Where do you read docs?

Depending on what you’re looking up, there may be a core body of tools that you search the documentation of, over and over again, and for which StackOverflow is just a proxy for. My personal favourite for that is the Python docs, for finding the exact syntax of standard library functions like str.isdigit(), or pathlib.Path.mkdir().

I use duckduckgo, so I’m lucky to have a dedicated search term for that:

!py3 str.isdigit

or

!py path mkdir

these are called ‘bangs’, redirecting the search to the right website’s searchbox. Neat!

But as I tried to learn to work more and more offline, I wished I had these to look up without an internet search, so that I can do this in a train, or an airplane.

Initially, I downloaded the docs offline as PDF, but that was hardly searchable.¹

Enough teasing, let’s talk about today’s star: Zeal docs!

Introducing Zeal, a docset GUI

Zeal is free software, initially a Linux/Windows port of the (non-free + not gratis) MacOS app Dash, by Kapeli. Kapeli graciously accepted that Zeal reuse Dash’s docs source, named “docsets”, as long as Zeal doesn’t impede on the MacOS app’s monetization.

So, first, we select docs from a big list for download and indexing. After a short delay, we have all our docs at our fingertips, yay!

Combined with my preference of global keybind of F8 to open Zeal, we can pop a simple question to the docs really easily.

By default, a search like “str.find” will search across ALL docsets (across all languages/tools we selected), but searches can be confined to single docset via “python:str.find” or equivalent.

There are also IDE integrations like Emacs Zeal-at-point, or VSCode Dash plugin, which will open the app on a specific page, based on the text under cursor in your main text editor.

There are a few more tips & tricks on Zeal’s “Usage” page, like use of browser-style tabs (Ctrl+T to open, Ctrl+W to close) and search-within-page via Ctrl+F or Vim-like / vs back-to-toplevel search of Ctrl+K or Ctrl+L.

Inspecting the docset ecosystem

There are many aspects of this documentation system that I find appealing: it seems that these “docsets” are official documentation, lightly post-processed, mostly by providing precomputed search indexes, packaged for download. Updates are managed via a XML-based feed system, all provided by Kapeli.

The ‘docset’ format itself is apparently Apple’s ‘Documentation Set Bundles’: “directories with the HTML documentation, metadata in an XML-based property list, and a search index in a SQLite database”. Says the author of “doc2dash”, a third-party docset-converter for popular HTML docs generators.

Kapeli’s documentation around Dash docset generation guide is also fantastic, explaining how to get started converting whatever language’s native docs into docsets.

This is particularly interesting to me as I wish more projects were included!

Kapeli’s official docsets may be of the highest quality, but more obscure projects don’t get this treatment. So the community created more. These are the “user contributed docsets”, still hosted by Kapeli (who gives unlimited docset access to Zeal thanks to non-compete agreement regarding MacOS support). These unofficial docsets, of varying quality and freshness levels, can be browsed on a user-made site, letting you select individual “feed” (set of URLs to download updates from) for each docset you may want to grab.

Making your own docsets

Since docsets can be created by anyone, there’s nothing preventing us from packaging any HTML docs into docsets. And once aggregated into a feed, served over the network, these can imported into Zeal, even privately.

So it’s possible for entire organisations to publish internally the feed of their own private docsets, for all their internal tools, even while the rest of the world isn’t meant to see it outside corporate intranet!

To try this out, I’ve added “doc2dash” to my standard Python Project template, so as to build docs both in HTML format, and available in docsets. Locally symlinking the docs’ output folder to Zeal’s docset folder allows pretty fast iteration!

Conclusion

It’s interesting that the entire docset world is held together by Kapeli, because of their authorship of the original tool. I wonder if the community would flourish more, or shrink, if there wasn’t such a strong hand curating it.

We all wish for good documentation, but, nowadays, if I’m to use a project closely-enough to search docs multiple times a day, I wish docsets, and for more people to publish them!