-
Notifications
You must be signed in to change notification settings - Fork 92
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Haskell platform library docs need to be more user-friendly #104
Comments
Just realized that there may be something that would be easy to do that would improve them. There's already a wiki search box. Adding a link for each module that searches the wiki for that module name would be an easy way to find examples. |
Is this what you are thinking of: http://hoogle.haskell.org/?scope=set%3Ahaskell-platform - searches the docs, restricted to the platform. |
No, for two reasons. First, the search should be for module names (Codec.Compression.Zlib, etc) and not package names, and second, the idea is to search the wiki in hopes of finding examples as opposed to the stuff that's on the platform library docs page. Ah, this time I found an example URL: https://wiki.haskell.org/index.php?title=Special%3ASearch&profile=default&search=Codec.Compression.Zlib&fulltext=Search Not really that useful for this case, but if you try System.Random, you get links to pages providing examples of using System.Random. |
The search is for arbitrary strings, including module names, function names and packages. Showing a full list of packages is just what it shows you before you type anything. I think that if there are good docs for System.Random then there should be a link from System.Random to them - creating a wiki page for every module seems wasteful, but linking the good ones seems valuable. |
I agree. That's one of the things I had a vague idea of when I opened this issue. But that requires finding all the pages that use the module, figuring out which, if any, qualifies as "good documentation" - which I believe means more than just copying the Hackage docs, but providing examples of how to use the library - and then creating the link to it in the platform library docs. That seems like a lot of work. Adding a link in the haskell platform library docs that does the search should be easy (at least if you've got the dev environment set up. It failed to install the dependencies for me, so I punted on that). If there is a page whose name is the same as the module, you'll get that page, not the search results - which is probably as close to what we'd like as you're going to get. And the search results suggest creating said page, which may encourage people to write such a page. I'd certainly be willing to contribute some if I feel qualified to do so. This seems like a good way to prime the process of getting the links we'd actually like. |
the redesigned platform page we've had in place for a period doesn't seem to have a docs section, so i think we can just retire this bug. alternately related tickets on the platform subsite can be raised at https://github.com/haskell/haskell-platform |
Opening the platform library docs page gets three frames with no labels as to what they are. While two are pretty obvious - a module list and the current module - the third one is a bit confusing, and my be nothing more than the module title again.
It should also be possible to search the platform library docs to find what module I've already got installed that might do the job I need doing. This should not be a full-scale hackage, hoogle or stackage search, as there's little point in providing a "blessed" set of libraries if we're going to refer users to things other things instead. This is related to issue #79, but note that while the example of doing a search for a function in python DTRT by finding things in the python standard library first, doing that search on haskell functions tends to go to hackage.
The text was updated successfully, but these errors were encountered: