Tools for offline documentation?

Tools
1

Heya!

Lately I’ve been trying to less and less rely on internet while programming. Googling is quite energy dense, and I’ve been in a few places where there is very limited or no wifi, where I would love to be able to continue developing while offline. I also feel like the communities living with limited wifi access should still be able to program, and access to docs is a prerequisite to do so productively.

The tools I found for offline documentation were:

  • man pages
  • info pages
  • devdocs
  • dash
  • zeal
  • Scattered PDFs for some languages
  • tldr pages

But in general my experience is that it is hard to know where to look for documentation (without googling), with so many options available.

I’d love to know what tools this community uses, or ideas they have for making it better

2 Likes
2

I highly recommend having the source code for notable projects you depend on checked out locally for browsing while you work :slightly_smiling_face:

5 Likes
3

Dash is fantastic - I’ve been looking for a comparable Linux alternative, but to no avail.

1 Like
4

While I personally recommend just writing man pages, unless your environment has other specific conventions (like Go has Go doc comments), do note that it is quite possible and pretty common to distribute HTML in $prefix/share/doc/$name.

5

Only applicable for Rust, but cargo doc will build the documentation for all dependencies, direct or transitive, which will almost certainly already be in the local cache. very handy! you can turn this off with --no-deps if you don’t want that, that’ll only build docs for the current crate

2 Likes
6

I think this is basically it: https://zealdocs.org/

Zeal lets you download offline documentation for things like Python, Django, NodeJS, Java, Lua, PHP, OpenCV, Qt, Rust, VueJS, etc…

2 Likes
7

Oh sweet thanks, I’ll take a look.

8

@Marc you may find the work I’m doing with the Freedom Respecting Technology Initiative interesting then. See Freedom Respecting Technology: the Next Generation of Open Source, Free Software, Open Knowledge, Open Culture, and Technological Freedom for more info.

At any rate I’m of the opinion that what matters for offline documentation is that the complete set be trivial to enumerate and make clean useful copies of for offline study. Whether that’s Ramp Up material or Reference material. Whether it’s material intended for Users or Developers. (And don’t even get me started on how artificial the barrier is between the two. Using is programming in a very high level usually point and click oriented DSL.)

Regarding DevDocs, Zeal, and Dash I appreciate them but it sucks that we live in a world where there’s a market for them to exist. As FOSS maintainers we don’t owe our users any set of features. But the one thing we do owe them is actual openness which among other things means the ability to study the system offline. DevDocs et al are basically doing (sometimes successfully, sometimes not as it can be quite hard to fully extract the docs roght) what should have been the responsibility of the upstream FOSS project. Beyond that I won’t repeat what I said in the HackerNews comment at As glad as I am that things like DevDocs and Zeal exist I feel like ultimately t... | Hacker News

So long as people can trivially enumerate and obtain all the docs for offline study and they’re all in open formats that’s what matters. (I need open formats I can inspect with the viewer of my choice. I don’t want to be limited to Zeal’s underdocumented if at all docset format I can only look at in the janky viewer.)

The rest is relatively inconsequential by comparison.

Though for what it’s worth I try to keep my docs as simple and low tech as possible.

I will never write a man/info page when a simple plaintext file will do. I have better things to do in my life than wrestle with troff and texinfo frankly.

Sometimes the thing I’m working on is big and complicated enough to benefit from some of the structure offered by man/info. And I use that when I need it and not before.

Similarly don’t create a PDF or offline website when a man/info page will do.

And don’t create a Jupyter notebook or something even more dynamic and akin to an offline Smalltalk image unless you need to. Sometimes that literally is the best way to communicate the info you want to. And in those cases go for it.

But most projects frankly don’t need this. Keep in mind your users may not even have reliable electricity at home let alone Internet. The friendlier documentation is to say being printed out at say a library they can visit every so often the better.

Again folks keep shit as simple and low tech as possible. Don’t use an elephant gun to shoot a mouse.

1 Like
9

I appreciate editors/IDEs that show the docstrings of symbols near my cursor.

1 Like