Giters

agda / agda

Agda is a dependently typed programming language / interactive theorem prover.

Home Page:https://wiki.portal.chalmers.se/agda/pmwiki.php

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Migrate the Chalmers Wiki

lawcho opened this issue · comments

commented

Problems with the Chalmers Agda Wiki

  • The wiki contains out-of-date information
  • The wiki duplicates information from the user manual
  • Search engines still point traffic towards the wiki
    • Search Query: "agda proof assistant"
      • #1 on DuckDuckGo (17 Feb 2024, Utrecht)
      • #1 on StartPage (17 Feb 2024, Utrecht)
    • Search Query: "agda language"
      • #3 on StartPage (17 Feb 2024, Utrecht)
      • #4 on DuckDuckGo (17 Feb 2024, Utrecht)

Proposal

commented

I think ideally we should also have a user-facing front page that is not the user manual or the github page. It doesn't have to contain a lot of information, but just a short explanation of what Agda is plus links to the various other places. This is the main role that the wiki currently serves imho (albeit poorly).

commented

I update the "Download" page on the wiki, and the standard libraries' page is also updated.
We also use it to organise the Agda meetings.
Esp. the latter is not something that should go into the user manual. Thus, before we have an alternative where to host such content, we can't give up the Chalmers wiki.

That said, it would be nice to have a nice looking front page, just no one has taken this chore up ever.

commented

RE a user-facing "front page"

Yes, I agree that:

  • Agda should get one
  • It should not be "doc style"

However:

  • We could share infrastructure between the docs, "front page", paper list, etc.

Case study

LiquidHaskell uses mkdocs for all its user-facing documentation, including:

LH front page

Halfway through a LH blog post

This was implemented in 2021 (ucsd-progsys/liquidhaskell#1862),
previously LH had separate blog and docs (ucsd-progsys/liquidhaskell#1852).

Other features to copy from the LH docs:

  • .github.io domain
    • Shorter than .readthedocs.io
    • Not doc-specific
  • Programming animations on the "front page"
  • Modern look & feel (due to mkdocs)
    • Nav-bar
    • Real-time search bar
    • Keyboard shortcuts
    • Split ToC
      • Left: "sections in this page"
      • Right: "pages in this website"
    • "Back to top" button (that doesn't get in the way)
    • Misc. design: colors, layout, etc.
commented

Web pages mentioned in today's meeting: