DevDocs

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...

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'm still loving asciidoc. Loads of extensions too so I can have PlantUML and Mermaid stuff too

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

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.

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.

Aeroplane

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.

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

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!

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 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 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.

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

often a static website distributed using git.

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

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?

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.

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

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.

man pages?

I'm one of the few maintainers.

Updating docs to a new release is easy unless the documentation system (such as react.dev redesign) or design is rewritten. Some projects seem to do this on a regular basis.

Some documentation generators generate random class names (such as .gtWOdv, .ezMiXD, .gOhcvK on docs.npmjs.com by Gatsby) which makes cleaning the docs from superfluous content (such as on-page navigation) very cumbersome and flaky.

Monthly, we auto-generate a list of outdated docs, here is the latest: https://github.com/freeCodeCamp/devdocs/issues/2105

Help is always welcome. :-)

I'm thinking ChatGPT can probably do a lot of the heavy lifting in this cleaning step, have you considered integrating your app with OpenAI's API, or perhaps an open model like CodeLlama?

Do you realize how much money that would cost? "just throw AI at it" is often some of the most expensive words uttered lately.

And fixing all the tiny little mistakes that will litter everything

Isn't it better than fixing all mistakes?

It's probably better to just not have any mistakes to fix.

Isn't that wishful thinking?

"...but can't you just run it in the cloud?" :)

Would you run in your basement?

Probably a datacenter...

Your own?

Do you realize this app is used by OpenAI's target audience and they could be interested in sponsoring?

are they though? Seems like they're more interested in money than exposure at the moment.

Is there any discussion around eventually providing commenting like the PHP docs of old (I don't know what the PHP docs now look like off-hand as I write this)?

Not that I'm aware of. In a way this contradicts the minimalistic and offline approach.

I don't know what the PHP docs now look like off-hand as I write this

The styling and layout changed somewhat, but the content is pretty much the same, comments and all.

Today: https://www.php.net/manual/en/function.fgetcsv.php

15 years ago: https://web.archive.org/web/20081218125142/https://www.php.n...

This is a very frustrating app for me. It is one of the best document sources out there but has become unusable because it cannot retain my selection of documentation. Almost every other time I visit I have to start from scratch picking the stack I use. It's great but not great enough to keep doing that over and over and over ...

I don't have an issue with dropping cookies or local storage elsewhere. I'm on an updated linux chrome. Any ideas?

The enabled docs are stored in local storage. Are you frequently deleting your browser data? The enabled docs may also be exported as well as re-imported as JSON.

Use devdocs-desktop? There's a lot of webview wrappers that have a separate config folder, and store docs offline.

https://github.com/hardpixel/devdocs-desktop

Could you rate the documentation generators based on how easy they are to consume?

I'd like to know how Sphinx, Docsy, MkDocs, Docbook, etc. compare in terms of being easy to semantically extract.

I'd need to look up the individual scrapers for a fair comparison, since I tend to forget/mixup the challenges. Some scrapers have been around for 10 years and only required little updates.

In general the more native HTML elements and the more descriptive CSS classes are used the easier it gets. Disadvantageous is when great parts of a doc page are built using JavaScript, e.g. when the whole nav is generated dynamically as the nav is typically the source for categorization/grouping on devdocs.

How can I help get playwright in there?

Here's how to add a new scraper: https://github.com/freeCodeCamp/devdocs/blob/main/.github/CO...

Or open an issue and wait for somebody else to implement the scraper.

How easy/tricky would it be to bring the pytorch documentation up to speed?

Thanks! I've literally had this tab pinned for years. It is awesome.

Hey simon04, I wanted to let you know that many many years ago the work of you maintainers made all the difference in my career and later my life.

Being able to read docs offline while commuting for some software I was pressed to work ended up being very important.

I just really wish you to know that albeit you may have not made a single $ by helping devdocs you are helping real human beings.

I was once asked in a technical interview how I’d do XYZ in some framework.

I said, “well, I’m not exactly sure, but I’d look up their API interface on devdocs.io to try and understand more…”

The interviewer had no idea what I meant, so we pulled it up on their laptop and they were blown away.

Granted… I didn’t get the job. But it was still pretty cool to spread some knowledge to the other side of the interview table for once!

Your contributions to this site is keeping it alive, and as a result it has inspired me to give a talk about my favourite updates to Python, since release 3.8. I could have found the data myself for sure, but you make it super convenient to compare all versions.

Well done!

Like an open source Dash (https://kapeli.com/dash). Noice!

There is already open source dash (https://zealdocs.or) although they don't provide Mac build because of an agreement to use some of dash's lists.

But you can build it on mac (https://github.com/zealdocs/zeal/wiki/Build-Instructions-for...)

typo in URL: https://zealdocs.org/

I've been missing Dash so much since I moved back to Linux, on my todo list is to create a Web based clone, that supports custom packages which was Dash's killer feature. And with top class Emacs integration, instead of having to context switch to a browser.

Currently focused on launching another project and I will have to get back to it, my productivity has tanked now that I constantly need to have a browser tab or three open on hexdocs.pm and MDN

Dash makes it really easy to pull docs from readthedocs.org also, this is something devdocs does not have.

I love devdocs, but I'm forever salty that they don't include C# as one of their languages.

if the C# docs have a flexible license , then you could add them

Unfortunately it seems to be the opinion of whoever controls the devdocs language requests[1] that the MSDN boilerplate license[2] is not permissive in this regard. However, devdocs is notable enough that they could easily at least ask for the written permission.

[1] https://trello.com/c/PVnfdeaN/26-suggest-new-docs-here

[2] https://learn.microsoft.com/en-us/legal/termsofuse

Certain parts of Microsoft Learn are permissive, most .NET/C# documentation is Creative Commons Attribution:

* Conceptual docs: https://github.com/dotnet/docs

* BCL: https://github.com/dotnet/dotnet-api-docs

* ASP.NET Core: https://github.com/dotnet/AspNetCore.Docs

* WinForms/WPF: https://github.com/dotnet/docs-desktop

The C# language specification is unfortunately a bit fuzzier, but the conceptual docs above include what most people want: https://github.com/dotnet/csharplang/discussions/4855

The updated unified C# language specification is CC, but it's still catching up to modern C#: https://github.com/dotnet/csharpstandard

MS docs ar now on github. Licence lists "CC-BY-4 and MIT licence found" https://github.com/dotnet/docs/tree/main

Yeah, I saw that devdocs and the like don't include what was previously not cross platform and not popular for linux guys: C#, msbuild.

Used this on a 14 hour flight recently. It turned it from a wasted day to an insanely productive one. No distractions, and the docs were there to answer the occasional question.

It’s so good even if you just want to unplug.

Sounds fantastic. Sometimes the restrictions on what you can do are freeing.

What's the modern equivalent of a Linux netbook? I want a little machine that's too underpowered to browse the web so I have no choice but to concentrate. Maybe Chromebooks have taken that spot but I don't want more Google in my life.

Sounds like you want a refurbished older thinkpad. x230 with the classic 7 row keyboard. Max out the ram. Maybe replace the screen with a newer 13" panel?

There's a whole subculture of thinkpad-modders out there. If you're looking for a small formfactor, excellent keyboard, plenty of ports, not too pricy (inc mods), that might be your best option. YMMV.

Sounds great, except if I am able to mod it, that will be distracting on its own :)

As glad as I am that things like DevDocs and Zeal exist I feel like ultimately they are a crutch and indicative of a much larger problem in Open Source which I'm trying to address.

Now as a FOSS maintainer I don't owe anyone any particular set of features or bug fixes. BUT I ABSOLUTELY DO OWE THEM ACTUAL OPENNESS AND THE ABILITY TO STUDY THE SYSTEM PROPERLY.

Many FOSS projects frankly kneecap Freedom 1 with a sledgehammer for anyone who isn't a well off person with reliable Internet access. And I've been up to here with it for a very long time now.

For all my FOSS projects big or small my pledge is to give users complete and trivial access to the full Open Knowledge Set associated with them.

Not just the main program sources and executables, but built and source forms of any official documentation that exists.

Withholding any official documentation that exists from trivial and easy offline access in a useful form is fundamentally no better than withholding any part of the source code. Period. End of story.

My pledge for all my FOSS projects is as follows:

At the home page people within 30 seconds of having read the Elevator Pitch and decided they want to study the system properly will be able to trivially enumerate and initiate downloads for all educational information related to it whether that's source code or built forms of the documentation usable for study straight away.

How the Open Source Definition and Free Software Definition don't mandate something as common sense as this I don't know. Open Source and Open Knowledge should be for everyone, not just well off people with reliable Internet access.

Anyway that's what caused me to start the Freedom Respecting Technology movement. Thus if anything I said here resonates with anyone they should read https://makesourcenotcode.github.io/freedom_respecting_techn... to learn more.

That's a good idea, but I don't see why it deserves a manifesto, or the grandiose claims about being the "next generation" of open source.

Just ship your software with documentation. This was a good practice even before open source or the internet took off. Old school closed source software used to ship with physical manuals, and good quality software often had good documentation as well. Some OSS CLI tools do have extensive manpages, yet users often don't read them in their entirety. So it's not just a matter of shipping good documentation, it's also about making it discoverable and easy to use. This is where projects like DevDocs step in.

I absolutely stand by my claim that FRT is the Next Generation of FOSS for several reasons.

To begin with even now in the 2020s billions of people alive today have never once been on the Internet. Source: https://www.un.org/en/delegate/itu-29-billion-people-still-o...

Also billions more may have some kind of Internet but it's flaky. Sometimes very very flaky. They are systematically excluded from large swathes of the FOSS ecosystem.

So make no mistake, the scale of the problem is VAST. We're talking billions of people here that can be helped by FRT. Again, billions, with a B.

If all existing FOSS were transformed into FRTs overnight the world would be unrecognizably better by several orders of magnitude.

And yes we need a new manifesto/definition. FOSS standards have completely dropped the ball on this issue among several others. Do a ctrl+f for the word "offline" in either the Free Software Definition or the Open Source Definition.

Many FOSS implementations also drop the ball here. Happily some do the right thing. Sometimes deliberately which is beautiful to see. Often though it turns out it's accidental and one redesign of the site later I can't get docs for the latest version of the tool.

Oftentimes it's the small (sometimes subtle) details that make the difference between freedom and lack thereof and the FRTD exists to make sure they are covered.

Even seemingly simple things often aren't. Consider pointers, they're just a thing that stores a memory address, no big deal right, easy peasy, yet using them safely is the subject of at least several chapters in a book, and even calls for research into and implementations of safer approaches like those used by Rust.

And yes one of the details the FRTD addresses is the discoverability issue you mention with the man pages.

Say I'm a newbie that just learned there's a thing called the command line and I open my terminal. I see a Bash prompt, but I don't know what to do with it, or even that it's a Bash prompt. I don't know about the man command. I don't know about apropos. I don't know about GNU info. I don't know to try looking for info manuals if I can't find man pages. I just vaguely know from like the movies or something I have to type stuff, press enter, and then stuff happens.

I don't know anything yet. The fact that the man pages are on my system and will be available offline does all of bupkis for me at this point.

On Linux there's a man page called "intro" (and even though there's room for improving it) after which someone reads it they actually have a fighting chance of using the command line and knowing where to learn more. On OpenBSD there's a similar man page called "help" that does a similar job and starts the whole conceptual bootstrap chain. Yet nothing tells me to start my studies by running "man intro".

On Linux a one sentence message saying to run "man intro" to begin your studies of the command line would go a long way for example.

The difference between information and knowledge is often a few small bits of commonsensically placed metadata forming a conceptual bootstrap chain as well as one pointing to the chain's start. Not labor intensive on the part of implementers yet transforms the system from zero to superhero.

Or perhaps since William Shotts wrote an excellent book called The Linux Command Line, and it's licensed under Creative Commons such that it can be reproduced and included in Linux distributions, maybe there can be a pointer telling people to read that at wherever it's stored on the system instead because it's far superior to "man intro".

Again a one or two sentence message can make all the difference.

Those are noble goals, but I think your project ignores a few important things:

- The internet has become the primary distribution channel of software itself, not just documentation. How would a user be in the position to access software via the internet, but not its documentation? They can't purchase software offline in a brick and mortar store anymore, and physical media is pretty much dead. They would need to keep the software updated on a regular basis, and downloading a few kilobytes of documentation pales in comparison to downloading hundreds of megabytes of software. So the internet really is a requirement for most software, even for those that can function entirely offline, and most developers make this assumption.

- What fraction of those 2.9B people who are not yet online would a) use traditional computers instead of tablets and smartphones, b) be interested in OSS, c) actually have a need for and the patience to read documentation? I reckon that this is a very small percentage, constituting orders of magnitude less people than the billions you claim it is. Instead, most people would be better served by using intuitive devices and software that doesn't require documentation to begin with. Smartphones and smartphone apps have made computing more accessible to more users than personal computers, desktop operating systems and mountains of documentation ever did. The next generation of computing devices will be even more intuitive, and written documentation wouldn't even make sense to new users.

- The quality of the documentation is more important than how it's accessible. It doesn't matter if I can read documentation offline, if it's incomplete, incorrect or confusing. There are no manifestos that will make developers write good documentation. This is either something they care about and put effort in, or they don't.

- The advent of LLMs is making traditional documentation obsolete. Why would any user prefer going through a bunch of documentation of varying quality to find the information they need, when an LLM could give them the right answer tailored to their query, much more quickly and in a consistent language? LLMs make knowledge more discoverable than traditional documentation. Even projects like DevDocs will not remain useful for too long. Proprietary LLMs like ChatGPT can already do a decent job at this, and other products can be trained on specific documentation. Accessibility is still a hurdle, but this too will improve with local, offline and open source LLMs, lower hardware requirements, etc. Soon there won't be a need to write documentation at all, as AI will be able to answer any functional question about software directly, which it can already do to an extent. Once it becomes better at writing software itself better than humans, documentation as we think of it today will be even less of a necessity.

So I really don't think your initiative has as much importance, or will have as much of an impact, that you think it does and will. At best, offline documentation removes a minor inconvenience for a small subset of computer users _today_. And these users already have solutions like DevDocs and, increasingly, LLMs at their disposal.

Been relying on this site for years

First time I've come across it. It's great!

Oh yeah, having a one-stop-shop for docs that can act offline is so useful. It has an API and I a have Neovim plugin that provides its feature set in my running neovim instance.

If they were to get more mobile/platform-specific stuff like Apple docs, Android, Windows especially (all of the supported SDKS lol) it would be a magical place.

Now add the ability to comment on docs like the PHP docs and we're _really_ setting off

Only gripe here, and it's not a devdocs problem per se, is that Firefox deletes the offline documentation if you haven't opened devdocs in a while.

Is there any way I can turn that off, preferably on a per-site setting?

This site's cookies seem to be issued for some 2 months. You can extend cookies' lifetime in Firefox globally and per-site but a cookie can (and in most cases should) be invalidated on the server side.

Where's Java? I can't find it in the Preferences, or in the Trello board of suggested languages or incompatible licensees.

It's called "OpenJDK"

MDN[0] is usually my goto reference for frontend stuff. I know DevDocs has the offline feature, but frankly I can't develop without an Internet connection. I tried it, and failed terribly. Besides MDN, developers need quick access to Google and ChatGPT to go forward, quickly.

[0] https://developer.mozilla.org/en-US/

I was recently on a flight where the "wifi is down" and wanted to get some coding done. I already had some LLM models downloaded, so I quickly pulled down the fauxpilot repo and made sure I had everything needed for when we were in the air.

My expectations were really low, but I was surprised at how productive I was with just DevDocs and an LLM. I might have even been more productive than normal because there wasn't any internet distractions.

I love this tool, and it's one of the tools I recommend to a lot of my fellow developers and emphasize the importance of RTFM. Thank you so much to the maintainers for keeping this going for so long!

Love it and use it very often.

When programming on the go, I’ve found this to be useful. Especially if the WiFi is flaky.

I also enjoy having documentation consolidated. If man, mdn, and devdocs were combined into a single standard interface it would be a great boost to my productivity.

dedoc is an offline CLI tool to download, search , read devdocs from your CLI. great way to help avoid context-switching to the browser (which has it's own distractions)

https://github.com/toiletbril/dedoc

It's statically compiled in rust so you can download and install the binary

This is the resource I reach to whenever I need to find a Nix function.

I'm not familiar with this, can someone give some context? I assume this is all harvested from other sources and just gathered here? Or is there some original content? How up to date is it typically?

DevDocs but for Google Drive?

I daydream about a DevDocs to use as an index for our company Google Drive.

The goal being to create something like Notion or Almanac but without having to have a new place to write (google docs functionality is really great and hard to escape).

We currently use Google Sites but it's so clunky and the search will not search inside Google Docs.

Google Drive as is doesn't work as it is too full of too many things. Even well structured, it doesn't function as an Intranet, for us.

I think the answer is that one just waits for Google to make their response to Notion/Loop, but post this in case someone knows of something like that or sees this a different way?

FWIW, a little Vim plugin for searching DevDocs: https://github.com/romainl/vim-devdocs

Hey, folks. I'm running down my checklist before a long trip. I'm preparing by downloading language and API docs in case I want to do some development in the air and figured I'd share this great tool. It allows for easy offline documentation access for a lot of languages and APIs. I'm hoping to brush up on some Zig and maybe do something fun with Vulkan. Happy new year!

emacs integration: https://github.com/astoff/devdocs.el

I’ve had this as a pinned tab in my browser for many years. Probably the only thing that has stayed the same in my browser over that time.

How can I help get Playwright in there?

The lack of common lisp documentation underlines how difficult it is to find resources on how to use that language. Is the hardest googleable language I've learned so far.

This is awesome!! I use something similar on MacOS but it's a native app with offline support. The offline support is a neat feature but honestly these days if the internet is down I just don't do any development work...

- https://kapeli.com/dash

Love this tool. I use it daily via an Emacs package[1], and I found the workflow to be way smoother compared to dash-like solutions.

[1]: https://github.com/astoff/devdocs.el

Kind of amazed that while programmers’ whole game is to develop systematic solutions to annoying problems… our own most basic need hasn’t been really met this way?

For instance devdocs does not have a bunch of libraries that I use regularly (selenium bindings in python, etc). I also tried Dash but wasn’t able to just ‘get’ for eg the openai docs and had to go to their website. Meaning I was robbed of the cool features of dash, being able to quickly search structured content.

Just seems ironic.

This is amazing! Mad props to whoever helped get this running.

I would love to see C# in this list!

Getting quite a few 404s on various links...

I've been using DevDocs in Neovim through this plugin: https://github.com/luckasRanarison/nvim-devdocs

Works great, and don't ever have to leave my editor to read something

Awesome, this is a great project

Thank you. This is terrific. Wish I knew about it earlier. So much better than using web search engines when I know I'm only looking for results from official documentation. Also so much faster. I think I'll get a copy and run/host it locally.