search

ucsd-progsys / liquidhaskell

Liquid Types For Haskell
BSD 3-Clause "New" or "Revised" License
1.2k stars 139 forks source link

Why separate the documentation and blog? #1852

Open yanhasu opened 3 years ago

yanhasu commented 3 years ago

This project has both a documentation website and a blog website.

Both are run out of the ucsd-progsys.github.io domain, and contain some shared information (e.g. links to this repo and the online repl).

However, the sites are styled differently, and the documentation links to the blog but not the other way round.

The documentation also seems a bit more complete than the blog, except for the fact that the blog contains the blog posts as well as an animated splash screen (which are not to be found in the documentation).

I suggest merging the two sites so that newcomers can more easily find their way to relevant information.

ranjitjhala commented 3 years ago

hmm interesting idea ... I think the main challenge is that

  1. The docs are mostly just plain markdown links generated by mkdocs but
  2. The blog is mostly .lhs files with the type annotations etc.

Not clear how to combine? But maybe the main point is to make them clearly linked so from the one it is totally obvious how to get to the other?

yanhasu commented 3 years ago

I see three issues:

  1. Linking is poor, so newbies miss out on half the information
  2. Styles are different, suggesting that one of the sites is abandoned or unofficial
  3. Duplication of common information (tutorial, links, basic info) makes it harder to keep the sites up-to-date

I suspect that all of 1 and most of 2 could be solved by giving both sites a common nav-bar (containing all the links).

ranjitjhala commented 3 years ago

Good points, thanks! the tricky thing is that the sites are generated quite differently.

The blog by a custom script / hakyll and the documentation using mkDocs. Each has unique pluses.

Maybe we can somehow use the styles for the one in the other … or perhaps move the blog stuff into mkDocs …

On Sun, Jul 25, 2021 at 5:47 AM yanhasu @.***> wrote:

I see three issues:

  1. Linking is poor, so newbies miss out on half the information
  2. Styles are different, suggesting that one of the sites is abandoned or unofficial
  3. Duplication of common information (tutorial, links, basic info) makes it harder to keep the sites up-to-date

I suspect that all of 1 and most of 2 could be solved by giving both sites a common nav-bar (containing all the links).

— You are receiving this because you commented.

Reply to this email directly, view it on GitHub https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_ucsd-2Dprogsys_liquidhaskell_issues_1852-23issuecomment-2D886197153&d=DwMCaQ&c=-35OiAkTchMrZOngvJPOeA&r=r3JfTqNkpwIJ1InE9-ChC2ld7xwATxgUx5XHAdA0UnA&m=t_VML1m-Q-qNR9u7wcxbOZv5SnauSBDumgF1RjfAuiY&s=yatLUJVSU0UW-YVYpAEpx1NABTHPOQG7olccdpFyI1I&e=, or unsubscribe https://urldefense.proofpoint.com/v2/url?u=https-3A__github.com_notifications_unsubscribe-2Dauth_AAMS4OAUTJCD4EHIIR55V2LTZQBV7ANCNFSM473CKVFA&d=DwMCaQ&c=-35OiAkTchMrZOngvJPOeA&r=r3JfTqNkpwIJ1InE9-ChC2ld7xwATxgUx5XHAdA0UnA&m=t_VML1m-Q-qNR9u7wcxbOZv5SnauSBDumgF1RjfAuiY&s=9Eoxxt_1zp-4x9VInXcXRSz-7i795M1UWUUrgAQXBgc&e= .