![]() 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. ![]() 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. language:term Search on Zeal dd language term Search on DevDocs man term. 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 don't know why they're not using Pdoc, maybe they don't know about it. Devdocs parses the relevant documentation pages and stores them in a more structured way inside a browser database file. 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. (First to mention ChatGPT gets slapped with a wet fish. 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. 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. A search engine requires no setup and covers everything. 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. 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 wish this approach were more supported by those producing documentation.
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |