ProjectPythia / projectpythia.github.io

https://projectpythia.org
Apache License 2.0
32 stars 17 forks source link

Cookbook guide is inconsistent with latest template #433

Closed brian-rose closed 1 month ago

brian-rose commented 1 month ago

The section Update repository-specific text currently says that "tags" and "thumbnail" should be edited in _config.yml but these fields are actually in _gallery_info.yml.

brian-rose commented 1 month ago

Also I think this line is not needed and should be removed:

Edit the notebooks/how-to-cite.md file with your Cookbook title in the line, “The material in is licensed …”

because the boilerplate text is just "The material in this Project Pythia Cookbook is licensed ..." and that's good enough for most.

brian-rose commented 1 month ago

In general I think that some of the steps in the Cookbook guide can be reordered. I don't think it makes sense to ask people to fill out the CITATION.cff file until after content development. The guide should focus on getting people building content as painlessly and possible, and then follow up with additional steps for getting the Cookbook reviewed and listed on the Gallery.

brian-rose commented 1 month ago

One more point: when the repo is transferred to ProjectPythia org, there are quite a few URLs that need updating across multiple files. In many ways it would be simpler to encourage people to reverse the order: transfer the repo immediately, before running the trigger-replace-links action.

We should encourage people to see parking the repo in the ProjectPythia org just a simple way to express intentions to eventually have the work appear in the Pythia gallery, as well as inviting collaboration.

Review and acceptance into the gallery is an entirely separate step.

brian-rose commented 1 month ago

I will attempt a PR that reorders the instructions and resolves the inconsistencies noted above.

brian-rose commented 1 month ago

Our current guide also says nothing about the testing and publishing infrastructure, and how to interact with Pull Requests, previews, etc. I'm adding detail about this to the revised guide.