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.
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.
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.
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.
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)?
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?
Usually, you rent a cage/room in one. For all practical purposes, it is yours. I went into a few of our data centers at my old job. There'd often be entire areas dedicated to spares, scooters, or whatever people visiting there might need.
If you can afford to run in the cloud, you can often afford 2-3 times your max capacity in a data center. People ended up in the cloud because it was less expensive. Now that the demand for data center space has decreased, running bare metal is less expensive by a large margin.
Combine that with Kubernetes and Harvester, you can basically have your own cloud at a fraction of the cost. Now you just need actual sys-admins instead of AWS experts ... and they cost about the same.
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...
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.
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 :-(
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).
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.
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.
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.
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.
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!
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.
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.
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.
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.
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)
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
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.
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.
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.
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.
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.
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.
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.
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?
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!
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.
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?
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...
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
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.
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. :-)