search

stan-dev / sgb

Stan Governing Body issue tracker and meeting notes
4 stars 1 forks source link

Website overhaul #1

Open yizhang-yiz opened 2 years ago

yizhang-yiz commented 2 years ago

Website redesign has been in the wind for 2+ years.

The new website is currently tentatively commissioned by SGB 2021 to faber and friends, with SGB member Max Mantei liaisoning with Malte . There has been no update since Oct 2021 when covid took another turn.

Some history. The website was first tasked to Iman Ali in SGB 2020. The contractor back then made a proposal but was not selected (iirc due to cost). Duco Veen and Max Mantei from SGB 2021 proposed a candidate separately and Max' was used. SGB 2021 had two meetings with Malte.

We are given $4800 through NumFOCUS' small development grant for website redesign.

P.S. The small development grant is fairly straight forward to apply and get approved. We should do it regularly. The candidate for the current cycle is for Aki's TA in Global South program. @VeenDuco is the liaison.

bob-carpenter commented 2 years ago

Who or what is Malte? Despite the title, the "faber and friends" site is in German.

yizhang-yiz commented 2 years ago

Who or what is Malte?

One of the guys operating the company. @maxmantei can share more on the background.

maxmantei commented 2 years ago

Malte is @maltekiessling and part of Faber and Friends, a group of web designers and web devs based in Hamburg, Germany.

We asked him to port the website over to the Hugo Docsy theme.* So, that would just be part of the whole website redesign. It's also only part of the NumFOCUS grant, I should add.

*) The Docsy theme was identified as the most suitable one back in the day by SGB 2020 and we (SGB 2021) decided to stick with it.

mitzimorris commented 2 years ago

the current website, jekyll theme "so simple", is bad, but the theme is not the main problem - we need a plan for what content should/shouldn't be there, what should be on the landing page; how the nav should go, and how to link out to other sites.

porting the current website to a Hugo theme would be great, but if so, I would like to push for sending our $$ to URGs, since this would be one of the few things we could do w/r/t diversity.

my $0.02:

the GitHub repos for Stan docs (user guide, functions ref, ref manual, CmdStan manual) and the R and Python interfaces and modules are all being served via GitHub pages for those repos. they are all themed with content-appropriate look-and-feel. we should respect this.

this is especially true for the Stan documentation - all of the "pretty" themes are designed to look nice on your phone. I'm sure there are folks who are reading the docs on their phones. the problem is that if you go with such a display, you get one phone screen's worth of content in your browser as well. this totally sucks. there was a recent brouhaha on Andrew Gelman's blog when he had to switch to a newer (and more secure) WP format. it took a month or so and quite a bit of hacking to get it right.

here's what I think a visitor to the site should be able to find quickly:

of secondary importance:

historically, things got bogged down on discussions of the landing page. IMO, the mistake made was thinking that we needed to make the landing page into a pitch for Stan, overlooking the fact that if someone has navigated to the mc-stan.org site, they already know about Stan and given that, what more are they looking for? my best guess is that they're saying "this Stan thing sounds good, how do I get me some?" and therefore, information on how to download and install are key.

yizhang-yiz commented 2 years ago

Thanks to @maxmantei & @VeenDuco for the recap. The firm is working on a prototype and will focus on the landing page items. We all agree that the priority is to have a clean landing page, most importantly pointing user to download, doc, and forum. We also agree that Hugo (Docsy theme) makes it reasonably easy to maintain and move things around, and we don't want to overload it with too much content.

Max will follow up after having update from Malte.

storopoli commented 2 years ago

I agree with you Mitzi. One minor comment:

  • the latest version of Stan is Maj.minor.patch - links to download (for your interface)

  • discourse and documentation

  • upcoming events

Also how to cite should the included in the priority list for the website. Citations are important and they directly impact grants, fund raising and adoption.

mitzimorris commented 2 years ago

Also how to cite should the included in the priority list for the website. Citations are important and they directly impact grants, fund raising and adoption.

good point - this page is pure very confusing and indirect: https://mc-stan.org/users/citations/ we should put together something like Google scholar - so that folks can just download the latest citation.

looking through various bibliographies from grants and papers:

@misc{stan2021users,
  title={{Stan User's Guide}},
  version={2.26},
  author={{Stan Development Team}},
  url = {https://mc-stan.org/docs/2_26/stan-users-guide/index.html},
  year={2021}
}

@misc{stan-examples:2017,
    author = {{Stan Team}},
    year = {2017},
    title = {Stan Example Models Wiki},
    url = {https://github.com/stan-dev/example-models/wiki},
    note = {Referenced on May 19th, 2017}
}
storopoli commented 2 years ago

BibTeX and APA

bob-carpenter commented 2 years ago

That page is also out of date after we broke our unified manual into three pieces: user's guide, reference manual, and functions reference. I used to keep a list of papers citing Stan, but that got way out of hand.

I'd suggest the manual document type for BibTex.

@manual{stan-users-guide-229,
  title = {Stan User's Guide},
  edition = {2.29},
  author = "{Stan Development Team}",
  organization = "{Stan Project}",
  year = {2022}
}

This should really have a version field, but it only supports edition, and I'm not sure how that'll be rendered, so you maybe just want to use the version number inside the title.

yizhang-yiz commented 2 years ago

It'll show up like 2.29 edition. So it makes sense to put it in the title.

storopoli commented 2 years ago

If we put in the title is going to mess with citations. If we leave in the edition Google Scholar and other citation aggregators can recognize it is the same document being cited but different editions.

We should update our release workflow to change the edition field in the BibTeX and APA citation at stan webpage whenever there is a new release.

bob-carpenter commented 2 years ago

@storopoli Google Scholar is having a hard time with versioning. Will putting it in edition really help? Google has to infer the BibTex from citations because they don't get the BibTeX of papers (other than on arXiv). I merged a ton of these to help organize my own Google Scholar page, but they get added faster than I can merge.

mitzimorris commented 2 years ago

We should update our release workflow

whatever the decision is, release workflow will update some part of the citation - noted!

storopoli commented 2 years ago

@bob-carpenter, I honestly don't know the right answer, it was a hunch. But I think that if we keep everything static and change only year and edition we might be able to have less problems with citations in GS and other academic trackers.

spinkney commented 2 years ago

@yizhang-yiz I think we should move forward and put some criteria together that we want satisfied.

storopoli commented 2 years ago

Hey, @spinkney I am interviewing some candidates from my university next week. They are undergraduates with a lot of good references and experience with web development.

Here is the project scope:

image

bob-carpenter commented 2 years ago

I would strongly recommend designing the page content before worrying about the format. That is, sort out the pages, links, etc., and only then worry about how to present. I really dislike our current headings.

I would prefer not to have a huge NumFOCUS image on our landing page. I really dislike the "fiscally sponsored" language they use, as it makes it sound like they're giving us money rather than the other way around.

That template is hugely wasteful of vertical space, which is the main problem with our current template.

"Stan" should NOT be in all caps. Anywhere.

"CmdStan" should say "Shell" or "Command Line"---all the other ones list the modality, not the name of the interface.

Why would we want all those links on the bottom of our pages? And we definitely don't want to include ads for "Goldydocs", whatever that is.

storopoli commented 2 years ago

@bob-carpenter I agree with everything.

The image is just the CSS styling. I will also try to enrich the vertical space.