4 ms·
Some of the libraries need you to click into the docs for specific modules to get the full documentation for them. This confused me when I first set out. eg. P
by weavie 7y ago
Some of the libraries need you to click into the docs for specific modules to get the full documentation for them. This confused me when I first set out.
eg. Postgres Simple. This is the page you get to at first when you search for it:
https://www.stackage.org/lts-14.21/package/postgresql-simple-0.6.2 https://www.stackage.org/lts-14.21/package/postgresql-simple...
It looks like there is no documentation, just a list of modules.
Clicking on the Database.PostgreSQL.Simple module gets you to the docs:
https://www.stackage.org/haddock/lts-14.21/postgresql-simple-0.6.2/Database-PostgreSQL-Simple.html https://www.stackage.org/haddock/lts-14.21/postgresql-simple...
- whateveracct 7y agoThis is pretty standard practice. The landing page for a package is never where examples live (except for the README). Haddocks are used for examples & tutorials, and the top-level module or a documentation-only module ending in ".Tutorial" are often provided.
- weavie 7y agoSure. It just took a bit of getting used to, but could be the reason why a lot of casual developers looking at the language have the impression that the documentation is poor.
- whateveracct 7y agoThat's fair I guess but if someone just looks at a single landing page and draws a conclusion without even clicking around idk what to say
- lonelappde 7y agoRight, and that's the problem. We just had a massive thread about th importance of good landing pages. The package home page needs a README with links to wherever the good stuff lives. Look at how GitHub does it.
- anentropic 7y agoPart of the problem is that stackage.org does not have a nice design for reading docs, even when the author has written some like this. I'd love to see more Haskell packages using readthedocs or similar. But I imagine that stackage providing ugly docs for free as a side-effect of publishing the package discourages most from making the extra effort to have nice docs.
- lonelappde 7y agoNot true. Look at https://www.stackage.org/package/rio https://www.stackage.org/package/rio The only problem is that the readme is below the module list, and mostly hidden behind a Read More button.
- anentropic 7y agoI appreciate that the content is ultimately all there, and this particular package has made effort with docs. But "the only problem" in this design is... quite a bad design. I don't really understand the choice to hide the actual docs and make a tree listing of sub-modules the primary content on the page.
- anentropic 7y agoI'd also love to know what a 'haddock' is and why these docs are in a different format https://www.stackage.org/haddock/lts-14.21/postgresql-simple-0.6.2/Database-PostgreSQL-Simple.html https://www.stackage.org/haddock/lts-14.21/postgresql-simple...