Hacker News Reader

Comment by kaycebasques | Hacker News Reader

I just revisited my "SWEs want offline docs" blog post from a few months back: https://technicalwriting.tools/posts/offline-docs/

Is there any kind of technology similar to RSS that lets you announce that your docs are offline-consumption-friendly? I don't mean service workers or anything like that. I mean some kind of standardized format for enabling users to read your docs offline. All I've ever seen are PDFs and self-contained HTML sites packaged as a ZIP. Anything else? Half-baked idea, but just asking in case something already exists and is not on my radar...

View on HN

I don't know if there's anything better than a zip. For our website[0] which includes a bunch of docs for our game engine, Zig packages, etc. we just offer a link "offline version of this site" in the footer which is an ~80MB zip file.

I think the challenge with zip files is.. do you want all the images? do you want all versions of the docs, or just a specific version of the docs? It's hard to tailor the zip to the user's desire. But zip still seems to be the best.

[0] https://machengine.org/

I used to get a lot of good mileage out of firefox's ability to render sites out of zip files as in jar:file:///home/foo/site.zip!/index.html but they nuked that pretty recently :-(

Say what you want about Mozilla but they work diligently to remove every competitive advantage they have!

Not a complete answer, but I hope Markdown is or becomes the standard for offline docs and text for local/offline consumption. I only ever write in markdown anyway (usually with http://obsidian.md).

The closest thing I know of for a service like RSS to download documents is [Dash for macOS - API Documentation Browser, Snippet Manager - Kapeli](https://kapeli.com/dash).

There's also Zeal (https://zealdocs.org/) which is basically the same as Dash but open source and runs on non-Mac devices.

I first learned of Zeal several months ago...and i really like it. But, i forget about havign zeal installed and available, that my reflex is to instinctively reach for duck duck go, or stack overflow, or somesuch search engine, etc. So, i just gotta build up the habit. :-)

I understand completely. I even wrote an offline documentation browser [0] for Linux similar to Dash, and I reflexively search online too. It's a hard habit to break, but I think it's a UI/UX issue.

0: https://github.com/techwizrd/tarpon

First of all, thanks for reminding me that i'm not alone! :-)

Secondly, kudos on tarpon; very cool!!!

Markdown is too anemic for documentation without extensions. Sure, you can make do, but I would rather wet standardized on something more powerful.

I agree. We need a standardized format with support for both structured (classes, methods, etc.) and unstructured (language overview) documentation..

I'm still loving asciidoc. Loads of extensions too so I can have PlantUML and Mermaid stuff too

CHM [0] is that, but it’s Windows-centric. Here [1] is one example of how it looks like in the native viewer. It’s a pity that Microsoft abandoned it. Some projects like AutoHotKey still use it.

[0] https://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help

[1] https://www.helpsmith.com/images/ss/chm-help1.png

I've been using Zeal. It doesn't have everything (yet?), but it's very relaxing.

I feel I may be alone, but emacs Info docs are really nice for this and stay oit of your way.

You are not alone. The Info viewer is much better than pretty much anything else IMHO.

Converting DevDocs.io to (a) Info and then (b) ElDoc would be absolutely fantastic.

(To make it clear: I love DevDocs.io, too, but it's still a browser and not Emacs.)

I see you already have several suggestions, but I might add: if you're already maintaining an online website for your docs, adding a cache manifest file is one way to do it.

EDIT: oh I just looked it up and actually that's been deprecated. https://caniuse.com/offline-apps

mirror the site and route to it via your hosts file?

There is a "docset" format in use by dash. https://kapeli.com/docsets

I mean you could ship GNU info documentation (for which I saw a quick mention in the Blog post, but thought I’d mention why I like it). These can be generated from a variety of sources, including markdown. When installed alongside your app, they would show up in the top level heading when launching info, making it nicely discoverable if you use info.

As a bonus, this means the documentation will always be up to date with the version you are using. I guess if you want to look at older or newer versions the downside is you’ll have to download the app.

> some kind of standardized format for enabling users to read your docs offline.

epub

An epub is a zip containing HTML files (more precisely, XHTML) and a few text files for metadata (mainly OPF for the global structure and NCX for a table of contents).

Apart from e-readers, there are many applications to read epub files on desktops or smartphones. Either stand-alone like koreader, or browser extensions.

I have an idea to make any documentation rendered in HTML to be processed. You could then have an application that could parse it, digest it, store it for offline access and have some kind of notification mechanism to let you know it changes.

Wait, why do we want offline docs? Good search is important, but there have not been many times in my last 10 years that I have needed something to be offline.

Some people don’t always have a fast (or any) internet connection when they work. In those cases it can be nice to have offline versions.

I imagine this is useful for a lot of people around the globe. I don’t use the broader internet a whole lot when I work, but I do use the official documentation pages when I forget how basic things, partly because my memory isn’t great but also because I work on multiple languages and don’t always remember how they each do specific things like splitting strings, reducing arrays or whatever. If I couldn’t just go to the official language documentation’s I’d need offline versions.

Even with fast internet, the other end is not always great. Trying to click through a few nodes of AWS documentation can be a quite bad experience some days. Especially combined with their not great search. That 5s here and there starts adding up if you're trying to research something you don't know very well.

Good search and offline docs are not mutually exclusive. Grab the HTML version of Python's docs for example. You can search through them totally offline thanks to a bit of JavaScript they include.

I use vim and am always reaching for 'K' (simplified version is it shows docs for whatever is under the cursor) first then 'man keyword' in another terminal and as a last resort the browser.

Online docs gets in the way if I'm working on something and just want quick info. Being able to always read it even without a connection is useful as well.

It's funny, I still fondly remember the Borland IDEs in the 90's when full, context-specific library documentation was a keystroke and less than a second away. All these advances in the power of an IDE, and searching google and picking the most relevant-looking result is the lookup paradigm now.

Offline is way faster to the point the way you interact with docs changes because of the lack of friction.

Aeroplane

often a static website distributed using git.

a locally runnable version of the online site can be started locally.

man pages?

Reply on news.ycombinator.com