6 ms·
I just revisited my "SWEs want offline docs" blog post from a few months back: https://technicalwriting.tools/posts/offline-docs/ https://technicalwriting.tools
by kaycebasques 3y ago
I just revisited my "SWEs want offline docs" blog post from a few months back: https://technicalwriting.tools/posts/offline-docs/ 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...
- sleepytree 3y agoNot 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 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 https://kapeli.com/dash).
- 0cf8612b2e1e 3y agoMarkdown is too anemic for documentation without extensions. Sure, you can make do, but I would rather wet standardized on something more powerful.
- djbusby 3y agoI'm still loving asciidoc. Loads of extensions too so I can have PlantUML and Mermaid stuff too
- SpaghettiCthulu 3y agoI agree. We need a standardized format with support for both structured (classes, methods, etc.) and unstructured (language overview) documentation..
- packetlost 3y agoThere's also Zeal (https://zealdocs.org/ https://zealdocs.org/) which is basically the same as Dash but open source and runs on non-Mac devices.
- mxuribe 3y agoI 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. :-)
- techwizrd 3y agoI 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 https://github.com/techwizrd/tarpon
- mxuribe 3y agoFirst of all, thanks for reminding me that i'm not alone! :-) Secondly, kudos on tarpon; very cool!!!
- slimsag 3y agoI 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/ https://machengine.org/
- mdaniel 3y agoI 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 :-(
- eitland 3y agoSay what you want about Mozilla but they work diligently to remove every competitive advantage they have!
- hiatus 3y agoThere is a "docset" format in use by dash. https://kapeli.com/docsets https://kapeli.com/docsets
- n49o7 3y agoI've been using Zeal. It doesn't have everything (yet?), but it's very relaxing.
- ymherklotz 3y agoI 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.
- madsbuch 3y agooften a static website distributed using git. a locally runnable version of the online site can be started locally.
- cortesoft 3y agoWait, 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.
- deleted 3y ago[deleted]
- devjab 3y agoSome 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.
- viraptor 3y agoEven 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.
- worksonmine 3y agoI 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.
- ParetoOptimal 3y agoOffline is way faster to the point the way you interact with docs changes because of the lack of friction.
- layer8 3y agoCHM [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 https://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help [1] https://www.helpsmith.com/images/ss/chm-help1.png https://www.helpsmith.com/images/ss/chm-help1.png
- mdaniel 3y agorelated: https://github.com/jedwing/CHMLib#readme https://github.com/jedwing/CHMLib#readme
- ParetoOptimal 3y agoI feel I may be alone, but emacs Info docs are really nice for this and stay oit of your way.
- mbork_pl 3y agoYou 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.)
- IggleSniggle 3y agoman pages?
- kevindamm 3y agoI 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 https://caniuse.com/offline-apps mirror the site and route to it via your hosts file?
- comatory 3y agoI 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.
- idoubtit 3y ago> 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.