Comment by omnicognate | Hacker News Reader

Comment by omnicognate | Hacker News Reader

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

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.

Glad you picked on pydantic. There is no reference doc whatsoever. The expectation is that you are supposed to learn by reading examples!

Back in the days of yore, software engineering teams led by greybeards used to be conservative in what dependencies they import into the projects. Those days are gone! Everyone imports everything today without any discerning eye.

> Those days are gone! Everyone imports everything today without any discerning eye.

That's even considered a feature today! If you don't have a language package manager that allows you to transparently import tons of stuff you've never heard of, then the language is considered crap.

Even the good old venerable Ada language (or rather: its most visible vendor) jumped on that bandwagon with https://alire.ada.dev/ :-(

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.

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.

Unfriendly and short-sighted (at least if you want your lib to be used, else why publish it?), is more like it.

But they spent hours writing all those examples. I think it's the opposite, it's a misguided attempt at being friendly. Short-sighted, I agree with.

Okay, I get you, and agree. Yes, friendly, but without thinking, at least some, at a higher level, what might be a better use of their (limited) time.

I think what you've said feels exactly right. Maybe a better Sphinx just needs to exist, it seems like pythons standards should make it pretty simple to write something where API documentation generation is so trivial there's no reason not to.

I normally do end up reading source code, but it often introduces unnecessary hassle because while it's great for "what does this function do?" type of stuff, it really falls down when you want to know "what type of functions fall under this module" since you end up navigating up and down through a lot of imports that make sense for code organization but are abstracted away at the point of use.

You can use the mkdocstrings plugin with mkdocs which will generate api docs from your functions and classes and their docstrings just like Sphinx does. It even supports inv files just like Sphinx so you can reference third party libraries in your own reference docs

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.

* https://technicalwriting.tools/posts/offline-docs/

* https://writethedocs.slack.com/archives/C6D77HJ4F/p168556139...

* https://www.reddit.com/r/technicalwriting/comments/13wvmbt

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

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.

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.

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.

Does IME == In My Experience ?

It does.

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.

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

Reply on news.ycombinator.com