search

PSLmodels / PSL-Infrastructure

The Policy Simulation Library consists of models and modeling tools that share the transparency standards and interoperability criteria set by the PSL-Infrastructure project
https://www.pslmodels.org
Other
18 stars 17 forks source link

slimmer catalog card and website #84

Closed MattHJensen closed 5 years ago

MattHJensen commented 5 years ago

Currently we consider pslmodels.org/catalog/model-a as model-a's catalog card.

I would like to propose that we begin viewing model-a's subsection of pslmodels.org/catalog as its card.

Currently these (very slim) cards only contain the project overview. We could add links to a Website, User Docs, Contributor Guide

The content on pslmodels.org/catalog/model-a (which we have been calling its catalog card) would move to pslmodels.org/model-a, and we would begin to think of it as model-a's website.

We would want to adopt a more typical website layout, perhaps with a home page like policychangeindex.org (albeit with different navbar links) and a PSL logo in a corner. We might consider using the sub domain model-a.pslmodels.org rather than pslmodels.org/model-a.

If model-a wants to host their own html from pslmodels.org/model-a, without using our rudimentary page builder, that would be fine so long as they conform to some basic layout and design color standards. If a they want to host their own website, completely separately from pslmodels.org, that is fine, too. The catalog card's website link would point to the website domain.

Once we are hosting project websites, it will be natural to also offer user docs and contributor guide hosting on pslmodels.org. We are already developing interoperability standards that would allow for parameters and data inputs and outputs to be documented nicely, like on Tax-Calculator's user site. We could piggy back on Sphinx and .md or .rst for contributor guides.

With these steps, we'll be in a world where a project can follow some flexible project organization standards and come away with a catalog card, website, user docs, contributor guide, and marketing platform.

andersonfrailey commented 5 years ago

Is the basic goal of this to give models more control over what their page looks like? We will have the catalog builder to create pslmodels.org/catalog and if the project elects to not create a custom page we'll create one as we're doing now. If they do choose to create their own page then it'll be up to them to keep it up to date and in line with some design standards. I'm on board with this idea.

In my opinion, pslmodels.org/model-a makes more sense than model-a.pslmodels.org.

In terms of the technical aspects of this, the first steps seems to be adding a field to register.json where a project can opt in or out of our page building scripts. If they opt in, we'll create their page every time we do updates. If they opt out, they'll need to open a PR with their new page. If they use some scripts to create their page I don't think it should be our responsibility to keep them in this repo and take on the associated maintenance burden.

Peter-Metz commented 5 years ago

After discussion with @MattHJensen, @andersonfrailey, and @hdoupe, we thought it best to allow projects to create their own, stand-alone websites, as opposed to giving each project a page on pslmodels.org. As such, #117 removes "Project Website" (which linked to a project's page on pslmodels.org) from the PSL Catalog. If/when projects make their own project websites, the "Project Website" link may be added back to the Catalog.

martinholmer commented 5 years ago

@Peter-Metz and @MattHJensen, What is the rationale for banning the "dev_changelog" attribute?
It seems to have been removed in this PR from the "Allowed attributes" list in theTools/Catalog-Builder/catalog_builder/catalog.py file.

MattHJensen commented 5 years ago

@martinholmer, thanks for following along with catalog development. Based on your feedback and others', the PSL-Infrastructure project is slimming down the PSL catalog cards. The new catalog cards, which you can find at https://www.pslmodels.org/Catalog (soon to be pslmodels.org/catalog), are only intended to include the project one liner, project overview, project core maintainers, and links user documentation, a contributor overview, the most recent user changelog, code repository and, when available, webapp and project website.

As part of this transition, we will be updating the catalog registry requirements, establishing static links to each project's slimmed down card, removing the old catalog cards, opening PRs to already-cataloged projects to correspondingly slim down their PSL_catalog.json files, and switching to lower case for all pslmodels.org urls.

The purpose for slimming down the catalog card is to better stick with the library metaphor and to avoid competition with projects' own websites. In the future, if there is significant demand, the PSL-Infrastructure project may add a website-builder capability that will allow PSL projects to build standardized websites that are more extensive than and separate from their catalog cards, but in the meantime projects that desire separate websites need to develop them by themselves.

If you think it is important to keep a link to the developer changelog in the Tax-Calculator catalog card, I am open to adding that back as an option for projects to include in their catalog cards.

martinholmer commented 5 years ago

@MattHJensen, Thanks for the explanation in this comment. You said:

If you think it is important to keep a link to the developer changelog in the Tax-Calculator catalog card, I am open to adding that back as an option for projects to include in their catalog cards.

No, not really. Just wondered about the thinking behind all the changes.

Peter-Metz commented 5 years ago

Resolved by #117