📝 Notes and Ideas

[visortelle]

Ideas

• Show GitHub stars if package source code is hosted at GitHub.
• Store pages that a browser has visited and then dynamically present a list of packages and modules on the home page RFC: alternative homepage layouts haskell/hackage-server#725 (comment)
• interesting metrics RFC: alternative homepage layouts haskell/hackage-server#725 (comment)
• hoogle search widget RFC: alternative homepage layouts haskell/hackage-server#725 (comment) Mostly done here 1c4b441
• fetch data from GitHub https://github.com/haskellfoundation/volunteering and display lists of volunteers, mentors, projects, and speakers at the dedicated section on the home page. Plus links to create an entry on GitHub for each category.

TODOs

• Deployment. - deployed to Vercel
• Simple availability monitoring. - should be handled by Vercel.
• Data fetching optimizations. Use SSR stuff where possible. Use next.js' swr hook. More: here https://nextjs.org/docs/basic-features/data-fetching#fetching-data-on-the-client-side and here https://swr.vercel.app/
• Highlight code in Hoogle search results.
• Implement error handling react context.
• Show loading indicator for SearchInput results.
• "Switch to old design" button.
• Ligatures toggle
• Navigate over the search results using a keyboard. Arrows, Emacs's Ctrl + n/p. Go to the result page by pressing Enter. Hide search results on Esc.
• Ctrl + r keybinding for recent searches
• 🐞 Don't show search input results when returning back from other pages.
• ??? 🐞 Fix case when user wants to search / operator and others. Now it calls default browser action. Probably we need to create a list of allowed hot keys like Ctrl/CMD + A, Ctrl + n, Ctrl + p, Ctrl + e, etc. and prevent default for others.

TODOs after MVP launch

• Guides content.
• Integration tests using Cypress.
• Careful tests for SearchInput react component, particularly its stateful behavior on page switches.
• Code playground service. Seems like quite a big feature. I see it useful for live examples and to embed runnable Haskell code into educational online resources. Am I the only one here who likes playgrounds?

Need to figure out how many Haskell and estimate server workload. Figure out if haskell.foundation or another organization is ready to provide to compute resources for this feature. Rust playground is supported by a private organization - https://integer32.com/

• Search results client-side filtering. :t servant +:f module. +:f is a special characters sequence here. Looks safe, will see.

• Adapt for mobile devices.

• Review SEO stuff.

• Styled 4xx and 5xx error pages.

• Store package metrics stats. Uploads, downloads, packages count, etc. It can be interesting infographics in long term.

• Embed https://pvp.haskell.org/ content

• Dark mode

🎩

• Package versions page: squash "patch" versions into one.
  Example:
  given: 3.3.4, 3.3.5, 3.3.6, 3.5.3, 3.5.15
  display as: 3.3.6, 3.5.15

• Fetch and show reverse dependencies from here: https://packdeps.haskellers.com/reverse/pandoc

Tech debt

• Fix @hackage-ui/react-lib exports mess.
• Remove unused dependencies.
• Simplify npm link development workflow. Maybe switch to lerna.
• Maybe recheck bundle size.
• Global styles?
• Refactor app context

[visortelle]

From Gershom B in Slack:

also related though: haskell/hackage-server#986
#986 Implement PackageRank from lib.rs
A very impressive amount of research and thought here: https://github.com/rust-lang/rfcs/blob/master/text/1824-crates.io-default-ranking.md
It would be useful to add this as an explicit metric to sort by. :thinking_face:
https://github.com/haskell/hackage-server|haskell/hackage-serverhaskell/hackage-server | Oct 24th, 2021 | Added by GitHub

[visortelle]

Haddock

On JSON format:

• JSON Backend haskell/haddock#352
• Discussion: intermediate output format haskell/haddock#1420

[visortelle]

Hackage

• RFC: alternative homepage layouts haskell/hackage-server#725

[visortelle]

Some article: https://nunoalexandre.com/2018/02/04/redesigning-haskell-docs

Single Liberal Unified Registry of Haskell Packages

https://mail.haskell.org/pipermail/haskell-cafe/2018-January/128472.html
https://github.com/simonmar/ecosystem-proposals/blob/slurp/proposals/0000-slurp.rst
https://github.com/tfausak/slurp
haskell/ecosystem-proposals#4
https://www.reddit.com/r/haskell/comments/7s58id/slurp_a_single_liberal_unified_registry_of/

[ocramz]

Idea : make the suggested searches clickable, such that one can look them up without typing

[visortelle]

@ocramz, thank you. It's a nice little thing improvement.

Fixed here: ad61c6f

Please check, is it what you meant.

Edit: one more commit on it: d6d07cc

Now it works this way:

Screen.Recording.2022-01-09.at.4.05.51.PM.mov

[dpwiz]

What about readmes and chagelogs?

[visortelle]

@dpwiz will add soon.

[Martinsos]

A bit of feedback (in the right place I hope): When searching for a function by name/signature, I find it a bit problematic that initial result view doesn't show the package from which it originates. I know I can expand, but that feels a bit tedious and actually gives me too much information. I would love to just see the name of the package next to the each function.

Specific case: I was looking for withObject function from Aeson package, and I wrote it into the search bar, but then I wasn't sure which one to pick. But maybe this is a bad use case because I should have gone to Aeson package and tried to find that function there? Still, that would require some digging and searching it like this sounds much nicer.

Hope this helps, but certainly take with a grain of salt!

[visortelle]

@Martinsos I plan to add scoped search and fuzzy text filtering in found items in further releases.

Hope, it will solve such use cases as this one.

Basing on other plans in my backlog, I think it will took about two weeks.

[visortelle]

Consider an idea 💡

• Create a list of "scary" 😱 Haskell terms like Monad, Semigroup, Monoid, Applicative, etc.

• For each term, create a short overview article probably with visual illustrations, example problem, and an analogy of how this problem could be solved in JS or Java.

  It should be very brief, links to materials with detailed explanations should be provided.

  Store these articles as markdown files in the repository.

• When the user types such a term in the search input, suggest him the overview article at top of search results.

• Later this approach can be extended to mini how-to tutorials for search terms like Read a file, SQL, Postgres, Write to file, etc. In other words - things with industry-average engineers deal on daily basis.

• It should be something like a GitHub and markdown-driven wiki, targeting novice haskellers audience at the beginning.

• Showing these articles in search results should be enabled by default, but optional. Users should be able to disable it at any time.

• These articles should be available as a list on a dedicated page.

Writing all these articles seems like quite a big amount of work. I can prepare a list first, then start with a brief article each day. More experienced folks can review it.

Maybe it makes sense to take http://dev.stephendiehl.com/hask/ as a basis if the author doesn't mind.

Now it's just an idea. I'm not going to start it tomorrow.

[dpwiz]

Create a list of "scary" scream Haskell terms like Monad, Semigroup, Monoid, Applicative, etc.

So, Typeclassopedia?

For each term, create a short overview article probably with visual illustrations, example problem, and an analogy of how this problem could be solved in JS or Java.

But with braces and semicolons...

Well, but how does that concern Hackage, the Haskell package registry?

[visortelle]

Well, but how does that concern Hackage, the Haskell package registry?

It doesn't. As well, as search using Hoogle or the Community section that I want to implement on the home page.

Relevant question: https://twitter.com/qnikst/status/1480529992425558017?s=20

I started the project as UI for the Hackage two-three weeks ago, but since that, I decided to switch direction toward - what features a Haskell website should have to be useful for developers on a daily basis.

I'll rename the project at some point in time.

So, Typeclassopedia?

It's a great source of information on some topics, but I see how to make the entrance experience more smooth for Haskell newcomers.

Let discuss it when I'll provide example articles for at least several topics. 🙂

[Martinsos]

Well, but how does that concern Hackage, the Haskell package registry?

It doesn't. As well, as search using Hoogle or the Community section that I want to implement on the home page.

Relevant question: https://twitter.com/qnikst/status/1480529992425558017?s=20

I started the project as UI for the Hackage two-three weeks ago, but since that, I decided to switch direction toward - what features a Haskell website should have to be useful for developers on a daily basis.

I'll rename the project at some point in time.

So, Typeclassopedia?

It's a great source of information on some topics, but I see how to make the entrance experience more smooth for Haskell newcomers.

Let discuss it when I'll provide example articles for at least several topics. slightly_smiling_face

Does that mean that the goal is not any more to replace the existing Hackage UI? If so, that is a shame really, I was looking forward to that a lot, since it would make it much more approachable.

If instead you want to re-do the haskelll website, you should probably get in touch with people behind haskell.org (the haskell.org committee) and sync your efforts, since they are also looking into how to improve it, from what I know. Here is an example of an issue I opened there, the discussion shows which ideas they would like to address: haskell-infra/www.haskell.org#136 .

Personal opinion on the articles -> I think the biggest problem is really writing/curating them and then organizing them, while searching through them is a much smaller problem. Once articles/materials are there, it should be easy to organize them into wiki and put a search on top of it. There already exists a Haskell wiki, however it doesn't feel modern / up to date, so it doesn't really distill a lot of confidence as a learning resource (at least to me).

It seems to me like you are really fast and capable with creating the modern UI and improving developer experience, and it would be a shame to potentially loose the change you can do due to getting stuck with writing articles, which are not an easy thing to write, especially for topics such as Monad, Applicative and similar -> education is a much bigger, separate problem, then UI and UX/DX of getting started with Haskell, I think.

I understand these opinions are highly subjective and I don't presume in any way I have the right to suggest what you should direct your passion and time into, consider it just as an alternative view that might or might not bring some useful information to your efforts.

[visortelle]

@Martinsos don’t worry, I won’t stuck with writing articles.

In the my initial idea comment I wrote:

Now it's just an idea. I'm not going to start it tomorrow.

I won’t start it before completing packages and docs UI.

you should probably get in touch with people behind haskell.org (the haskell.org committee) and sync your efforts, since they are also looking into how to improve it, from what I know.

Before starting a discussion on coordinating efforts and involving more people, I’d prefer to have something to show.

I established an initial contact with @myShoggoth and @Bodigrim. Both are board members of the https://haskell.foundation/
I think at some point when my project will collect enough useful features, they could coordinate my efforts.

[visortelle]

@Martinsos I didn’t read the discussion you linked yet. On the road now. Will do today. 🙂

[visortelle]

@Martinsos I read the discussion you linked to. Overall I agree with you about the Getting Started stuff on haskell.org.

There is no goal to replace or improve existing haskell.org. It's a separate project and if it will be useful and will take a broad adoption, maybe this topic can be raised.

Does that mean that the goal is not to replace the existing Hackage UI? If so, that is a shame really, I was looking forward to that a lot since it would make it much more approachable.

Did I ever mention that the party was canceled?

My prioritized tasks now:

• In addition to the already released browser extension, finish VSCode extension. I see it as the fastest way to deliver useful stuff to a broader audience.
• Finish package page.
• Implement docs browsing functionality.
• Make the home page useful. Setup community activity feeds, including integration with https://github.com/haskellfoundation/volunteering
• Integrate with https://github.com/serokell/hackage-search full-text search. I asked Serokell about using their API Can I consume you public API? serokell/hackage-search#25 , they don't mind if I'll mention that search results are provided by Serokell.

Next step I see implementing Haskell playground to have the ability to make live examples in package documentation and education materials. Only after that, I'll start the first experiments with the mini-articles.

If you want to help with code or advice on some of the mentioned stuff, you are welcome. 🙂

[Martinsos]

@visortelle sounds good! As I said, don't mind me, you should do whatever you feel you are most excited about, but since you are building this is in public I thought you could benefit from an additional opinion/perspective.

Sounds good to me, and I am really excited to see the results!

I will keep an eye on the project and if you create issues that could be taken by others I will try to find one that I can help with, if time permits.

[visortelle]

if you create issues that could be taken by others I will try to find one that I can help with, if time permits.

@Martinsos there is one issue that doesn't require any coding: #8