@kanishka said in a different thread:
If the documentation and tutorials are very thorough for each library and each library presents a gradual path for haskell beginners to haskell experts to make use of the library without having to read the source code or understand all the advanced aspects of haskell to start being productive
Which reminded me of how unfriendly hackage looked like when I started writing Haskell:
There’s sometimes a note before everything else, but sometimes all the text is below the modules hierarchy and is kind of skewed to the right as if it was a quote (it is indeed quoting the README…), as if it didn’t quite belong to the documentation. Sometimes there’s no text at all!
OK, so I’d then click on the modules and be confronted with types (lots of them) and often small and succinct descriptions. Sometimes the “main” (for some definition of main) module had a bigger description covering the library. Sometimes libraries have good usage examples.
This is no longer what I feel. If I find a library in hackage I’ll read the package description and README if they exist, then jump on to the modules – I know where to go and what to do.
Ironically, now that I have the ability to change/argue that first experience, I technically no longer have that need.
I hadn’t given any though until now: I do want to change that experience! (Then again, was it only me? I’m bringing this up so do speak up)
I want to ask: what’s being worked on by the community regarding friendlier introductions to things in general, and libraries in specific?
Some of my thoughts: (note that it’s quite possible I’m not seeing bigger pictures, previous attempts, etc, so read my opinionated opinions knowing I’m not writing absolute truths, but rather commenting on what I see from the surface)
When searching for a library to do X in Haskell, it’s common for me to get an outdated Haskell wiki page mentioning a few abandoned alternatives. Why try to maintain curated content on ever changing resources? Wouldn’t a better “search engine” indexing better (structured) documented packages (perhaps even making community contributions easy!) be a more maintainable solution?
By structured I mean standardising/defining/outlining the information that’s usually in the wiki and making it part of the package (the same kind of structured information, but so that it’s maintained separately from the wiki and close to the package)
And by community contributions I still mean for each package to maintain their own “wiki entry”, but having it easy for contributors to suggest information for the package description, examples for methods, etc
Summarising: Would it be better to decentralize the Haskell wiki parts regarding packages and have each package owning its structured documentation, and having a better “search engine” putting together separate package entries into something that would resemble the original wiki page?
On hackage specifically:
What are the thoughts on having this structured documentation idea that brings the good bits of the libraries wikis and as suggested by @kanishka maybe a structured/standard approach to incremental documentation?
I think I might’ve let the “pen” run too free… ahaha 