search

RSE-Sheffield / fair4rs-lesson-setup

Instructions for setting up a lesson repository for the University of Sheffield FAIR4RS training programme
Creative Commons Attribution 4.0 International
1 stars 0 forks source link

Testing feedback #18

Closed ns-rse closed 8 months ago

ns-rse commented 8 months ago

Ran through the instructions creating ns-rse/workbench-test as I was checking the instructions for RSE-Sheffield/uos-varnish so figured I should run through these too.

I realise a lot of this is copy and pasted from the Carpentries Workbench instructions and I'll look to contribute patches up-stream but this is now material that is divergent and considerably different so noting these here.

fair4rs_config.patch

This applied perfectly :+1: . Some suggestions on fields below.

README.md

Edit configuration, citation metadata, contributing guide and licence

Instructions are clear but I was wondering if we could tweak the Markdown

Perhaps include line numbers in the bulleted points.

config.yaml

This file contains global parameters for your lesson site. Individual fields within the file are documented with comments (beginning with `#`). At a minimum, you should adjust all the fields marked `# FIXME`:

CITATION.cff

This file contains information about citing this repository. At a minimum, you should adjust all the fields marked `# FIXME`:

CONTRIBUTING.md

Would it be helpful to be consistent and use # FIXME in this file? On first viewing I struggled to see these and having them stand out might help. If so then...

Update links to GitHub repository and issues, marked `<!-- # FIXME -->`.

...and we would need to remind people to remove these from the Markdown as they wouldn't be ignored.

Also we know these are likely to be hosted on GitHub so the patch should probably have...

[repo]: https://github.com/<account>/<repo>                 <!-- # FIXME -->
[repo-issues]: https://github.com/<account>/<repo>/issues   <!-- # FIXME -->

Commit changes to configuration, citation metadata, contributing guide and licence

Could use the following instead, its more succinct for people to type and adds all tracked files that have been touched/updated.

git add -u

Activate GitHub Pages for your repository

I know this is a copy and paste (and I will at some point contribute this up-stream) but it would perhaps be useful to mention that under Settings > Pages that the Source field should be set to Deploy from branch prior to stating what that branch should be.

Update README

I think this section would perahps fit beetter under Edit configuration, citation metadata, contributing guide and licence so that it is included in the first commit people make. Perhaps to shorten the section title it could Update Files with Metadata.

tdjames1 commented 8 months ago

[Edited to add a couple of points]

Thanks, Neil, this is great feedback.

config.yaml

The created date has # FIXME appended to the line suggesting it needs modifying but it isn't listed in this section of the README.md. Should we ask people to enter the date the lesson template is first used and work begins or to leave until material development is ready to be used?

Good idea to add some guidance here, I'd probably go with development complete date (but that requires the person to remember that they need to do it) so maybe hedge it by saying enter the current date and edit later?

url is listed but no # FIXME at the end of the line. Maybe we could perhaps be helpful and instruct people on what the URL is likely to be based on what account/organisation the repository will be under, if its RSE-Sheffield then it will resolve to https://rse.shef.ac.uk/.

I didn't add a FIXME because I believe it defaults to .github.io/ (the comment above in the config is meant to suggest this) so could remove it from list of things to edit.

I notice with the updates to (uos-)varnish that the Cite link is now empty and it looks like the configuration file needs to specify the citation file name. (Also the spacing for those links is broken, but I can't figure out why!)

CONTRIBUTING.md

Would it be helpful to be consistent and use # FIXME in this file? On first viewing I struggled to see these...

Ctrl-S FIXME :smiley:

and we would need to remind people to remove these from the Markdown as they wouldn't be ignored.

I'm not that keen on introducing breaking changes to the patch.

Also we know these are likely to be hosted on GitHub so the patch should probably have...

I did consider making that change but opted to leave as is to keep the changeset as minimal as possible.

Commit changes

git add -u

:+1:

Activate GitHub Pages for your repository

I know this is a copy and paste (and I will at some point contribute this up-stream) but it would perhaps be useful to mention that under Settings > Pages that the Source field should be set to Deploy from branch prior to stating what that branch should be.

Fair point, although I think it's the default?

Update README

I think this section would perahps fit beetter under Edit configuration, citation metadata, contributing guide and licence so that it is included in the first commit people make. Perhaps to shorten the section title it could Update Files with Metadata.

Good idea!