5 ms·

I wish this approach were more supported by those producing documentation. Looking things up in reference docs is one of those cases where reducing friction yie

I wish this approach were more supported by those producing documentation. Looking things up in reference docs is one of those cases where reducing friction yields huge productivity benefits, but I still end up using a search engine (Kagi now as Google hides authoritative reference docs under a pile of poor-quality, irrelevant spam these days). I've tried Zeal multiple times but while the app is nice and many of the docsets are good, many of them aren't good: badly formatted, badly indexed, outdated or simply nonexistent. A search engine requires no setup and covers everything. It's just so horribly slow. If we were grown ups, all software authors/vendors would be providing their reference docs in a standardised form, findable, downloadable and displayable by a wide range of tooling, consistent across languages, IDEs and platforms. Zeal is the closest we have, and it's a noble effort, but IME it doesn't solve the problem well enough to be useful because there's no buy-in from the people producing the docs. (First to mention ChatGPT gets slapped with a wet fish. Just try me.)

kaycebasques 3y ago
I'm a technical writer. I have felt this a lot myself. It is very comforting to know that the man pages are always there if I need them. Same with the Rust docs. And Beej's Guide to C Programming (I downloaded the PDF). Conversely, it kinda sucks to have to rely on a website to get info. I will kick off a discussion around offline docs in the technical writer communities that I'm part of.
- kaycebasques 3y ago
  * https://technicalwriting.tools/posts/offline-docs/ https://technicalwriting.tools/posts/offline-docs/ * https://writethedocs.slack.com/archives/C6D77HJ4F/p1685561398509429 https://writethedocs.slack.com/archives/C6D77HJ4F/p168556139... * https://www.reddit.com/r/technicalwriting/comments/13wvmbt https://www.reddit.com/r/technicalwriting/comments/13wvmbt
- bippihippi1 3y ago
  rust docs is one of the reasons it's the so nice to use. Javadocs are nice but so many libraries have their own format. Everyone using the same thing makes it so much better
whitten 3y ago
Does IME == In My Experience ?
- jmholla 3y ago
  It does.
- omnicognate 3y ago
  Yes. Apologies. I'm used to using that in chat with people familiar with it, but shouldn't have here. Random unexplained acronyms are annoying.
nerdponx 3y ago
And on the other side of things, there's a growing trend in the Python library ecosystem of simply not writing reference documentation at all, instead providing either a few or a lot of user guides and tutorials, and directing users to either read those and try to interpret their mysteries, or expecting users to read the source code and interpret those mysteries. It makes no sense to me. The Pydantic issue tracker for example is absolutely full of people simply trying to figure out how to use the damn thing.
- benrutter 3y ago
  Yeah, I was struggling with this trend earlier when looking at the Textual library, which has amazing examples but doesn't seem to have very detailed full API documentation. I wonder why this trend is happening, especially when python in particular has a bunch of standards and tools to make generating full API docs pretty straightforward.
  - nerdponx 3y ago
    I think it's partly because Sphinx is clunky and people have been using MkDocs instead, which I believe either doesn't generate anything from docstrings at all, or didn't until recently. I don't know why they're not using Pdoc, maybe they don't know about it. I also get the sense that there is a growing movement among programmers that API reference documentation is useless, or not worth putting effort into, because it's possible to go out of sync with the code and "nobody reads that anyway". I've heard people say things like "if you're advanced enough to read reference documentation, you're better off just reading the source anyway." It seems to be rooted in some kind of combination of extreme cynicism, a distorted sense of how people who aren't raw beginners learn to do things, and of a kind of false minimalism, wherein API documentation is old fuddy-duddy stuff for Java and C++ developers, and the new friendly easy way is to just read the examples. Such libraries also seem to exhibit a poor separation of public and private interfaces, so maybe it's just a reflection of people being bad at designing libraries.
    - fuzztester 3y ago
senko 3y ago
In hope I avoid getting slapped with a wet fish, I would love to see a future version of Zeal with an option to ingest the docsets into a vector database and "chat" with it using a (local) LLM that's fine tuned for answering technical docs questions. To stay on topic, I feel the pain: Zeal is so nice I curse when I need to look up something in the docs that aren't supported (Django REST Framework, in my case), since they use a different doc framework and can't be easily prepared for Dash/Zeal.
- worldsayshi 3y ago
  Somewhat related: wonder if using a local LLM could make it more feasible to federate reference documentation by translating various doc formats into a common one.
bombcar 3y ago
https://www.kiwix.org/en/ https://www.kiwix.org/en/ Has some nice stuff for offline, but it’s not really optimized for it.
macjohnmcc 3y ago
I miss the documentation that was part of Microsoft MSDN subscription. I now work in a sandboxed environment and cannot access help for the APIs from within that environment so something that I can download in it's entirety and get into that environment would be ideal.

kaycebasques 3y ago

I'm a technical writer. I have felt this a lot myself. It is very comforting to know that the man pages are always there if I need them. Same with the Rust docs. And Beej's Guide to C Programming (I downloaded the PDF). Conversely, it kinda sucks to have to rely on a website to get info. I will kick off a discussion around offline docs in the technical writer communities that I'm part of.

kaycebasques 3y ago
* https://technicalwriting.tools/posts/offline-docs/ https://technicalwriting.tools/posts/offline-docs/ * https://writethedocs.slack.com/archives/C6D77HJ4F/p1685561398509429 https://writethedocs.slack.com/archives/C6D77HJ4F/p168556139... * https://www.reddit.com/r/technicalwriting/comments/13wvmbt https://www.reddit.com/r/technicalwriting/comments/13wvmbt
bippihippi1 3y ago
rust docs is one of the reasons it's the so nice to use. Javadocs are nice but so many libraries have their own format. Everyone using the same thing makes it so much better

whitten 3y ago

Does IME == In My Experience ?

jmholla 3y ago
It does.
omnicognate 3y ago
Yes. Apologies. I'm used to using that in chat with people familiar with it, but shouldn't have here. Random unexplained acronyms are annoying.

nerdponx 3y ago

And on the other side of things, there's a growing trend in the Python library ecosystem of simply not writing reference documentation at all, instead providing either a few or a lot of user guides and tutorials, and directing users to either read those and try to interpret their mysteries, or expecting users to read the source code and interpret those mysteries. It makes no sense to me. The Pydantic issue tracker for example is absolutely full of people simply trying to figure out how to use the damn thing.

benrutter 3y ago
Yeah, I was struggling with this trend earlier when looking at the Textual library, which has amazing examples but doesn't seem to have very detailed full API documentation. I wonder why this trend is happening, especially when python in particular has a bunch of standards and tools to make generating full API docs pretty straightforward.
- nerdponx 3y ago
  I think it's partly because Sphinx is clunky and people have been using MkDocs instead, which I believe either doesn't generate anything from docstrings at all, or didn't until recently. I don't know why they're not using Pdoc, maybe they don't know about it. I also get the sense that there is a growing movement among programmers that API reference documentation is useless, or not worth putting effort into, because it's possible to go out of sync with the code and "nobody reads that anyway". I've heard people say things like "if you're advanced enough to read reference documentation, you're better off just reading the source anyway." It seems to be rooted in some kind of combination of extreme cynicism, a distorted sense of how people who aren't raw beginners learn to do things, and of a kind of false minimalism, wherein API documentation is old fuddy-duddy stuff for Java and C++ developers, and the new friendly easy way is to just read the examples. Such libraries also seem to exhibit a poor separation of public and private interfaces, so maybe it's just a reflection of people being bad at designing libraries.
  - fuzztester 3y ago

senko 3y ago

In hope I avoid getting slapped with a wet fish, I would love to see a future version of Zeal with an option to ingest the docsets into a vector database and "chat" with it using a (local) LLM that's fine tuned for answering technical docs questions. To stay on topic, I feel the pain: Zeal is so nice I curse when I need to look up something in the docs that aren't supported (Django REST Framework, in my case), since they use a different doc framework and can't be easily prepared for Dash/Zeal.

worldsayshi 3y ago
Somewhat related: wonder if using a local LLM could make it more feasible to federate reference documentation by translating various doc formats into a common one.

bombcar 3y ago

https://www.kiwix.org/en/ https://www.kiwix.org/en/ Has some nice stuff for offline, but it’s not really optimized for it.

macjohnmcc 3y ago

I miss the documentation that was part of Microsoft MSDN subscription. I now work in a sandboxed environment and cannot access help for the APIs from within that environment so something that I can download in it's entirety and get into that environment would be ideal.