Carpentry@UiO websites: can we have 1 (outside UiO domain) website?

[naoe-tatara]

Board discussed Carpentry@UiO relevant websites. Now under UiO/UB, we have pages relevant to the community (https://www.ub.uio.no/english/writing-publishing/dsc/carpentry-uio/index.html) and workshops (https://www.ub.uio.no/english/courses-events/courses/other/Carpentry/), but only designated UB staff can edit them, and thus it is not optimal to have only these pages.

Meanwhile, Carpentry@UiO has the following websites, in addition to use of GitHub repo as source of various important information, such as onboarding.

https://uio-carpentry.github.io/ https://uio-carpentry.github.io/studyGroup/ https://governance.readthedocs.io/

Ideally, it is best to have everything in one place, but if this is not reasonable/possible at least as few places as possible. From user point of view, what is the optimal solution here?

Personally, I see the following advantages and disadvantages for each option:

• ReadtheDocs format (the one used for governance)
  • Advantage: it is very neat and nicely fits manual-type of documents, probably also for archiving minutes or reports as well.
  • Disadvantage: Migration from MD file is a bit difficult?
• MD-based solution, such as "bookdown" (ex. https://cdh.carpentries.org/)
  • Advantage: Based on R Markdown. Could be more people in the community who knows about this well?
  • Disadvantage: change in the URL?
• Using GitHub repos as they are
  • Advantage: not much works need to be done
  • Disadvantage: not very visible, difficult to find information?

[Teebusch]

I agree with you Naoe, that there are too many Carpentry @ UiO websites. I'm actually surprised by how up to date the information on all of them is! I suppose that's only thanks to your and Annika's ability to keep on top of this chaos!

My thoughts on streamlining our web presence:

What?

I think we should have two websites:

1. the UiO website(s) should be our official point of contact with "outsiders". It should have all the information about workshops and "who are we". All that people need to find workshops, learn about the Carpentries, contact us and sign up. I understand maintenance by non-UiO members is not possible, but I wonder if that is actually a problem, given how things are organized at the moment? Having the UiO branding is important, I think.

   • Ideally, the two pages on the UiO website (one, two) should be one, but I understand there might be reasons for this, and the separation into "info" and "workshop announcements" is not too bad.
   • (Sidenote: there are a couple of missing images in the workshop list)
   • The UiO site should link to our Github page https://uio-carpentry.github.io/ for the study group and other day to day activities (see below).

2. https://uio-carpentry.github.io/ should be the home to "less official" stuff and "day to day" activities, such as governance docs, board meeting minutes, but also study group activities.

   • We should avoid duplicating content from the UiO website (!) In particular: What is the value of maintaining the past course list and future announcements on Github?
     • I would make the study group related content part of https://uio-carpentry.github.io/ The study group isn't active enough to need its own website, and it is better if there is only one site to maintain.
     • I also suggest to incorporate the governance docs into https://uio-carpentry.github.io. The URL https://governance.readthedocs.io/ sounds like it's not specific for UiO Carpentries. From what I can tell it's basically one medium-length markdown document split across multiple files, with a nice template. Migration from .rst to .md shouldn't be a problem.

How?

• I'd use a markdown-based static site generator. In combination with GitHub Actions, setting up a site that rebuilds automatically when changes to the markdown are made is straightforward. Personally, I like Hugo. It builds quickly, isn't too hard to customize and has lots of themes.
• We could use R's blogdown or distill. That way, people who are comfortable with using RStudio have a nice IDE to make changes to the markdown, submit pull requests, etc.
• I could fork the current website repo, set up a Hugo site there, add the governance, study group content and meeting minutes from the organisational repo, ans then make a PR. But we need to decide together what should be on that site.

[naoe-tatara]

Awesome!! Thanks for the great suggestion and volunteering! Looking forward to seeing your HUGO based website 🥰

Reg. 1-1, as it was explained at the board meeting. 2-2, i have been aware, but actually on the event page, the figure is shown. So i have no idea how to fix them. Can anyone help here?

[arockenberger]

Hei!

To give my two cents to this discussion:

I agree that the University Library needs the website(s) hosted at UiO for workshops, incl. an overview website like the one we have now. This is at least as important for how we communicate about the Carpentries workshops and to our learners as it is internally for how we communicate our efforts to the library which generously pays the annual membership.

When it comes to the materials on GitHub, I see the following scenario:

• the "backlog" of our workshops, now its own repo under (https://github.com/uio-carpentry/uio-carpentry.github.io), could be moved into (https://github.com/uio-carpentry/organisational), i.e. the "index.md" file that contains the backlog could be moved into https://github.com/uio-carpentry/organisational/reporting. It's mainly been used for keeping an overview of what we have done, our "history" so to speak.
  • ACTION: move index.md to https://github.com/uio-carpentry/organisational/reporting, rename to backlog.md
  • ACTION: disable GitHub Pages, update README.md with info about move and archiving the repo and then archive (https://github.com/uio-carpentry/uio-carpentry.github.io)
• the governance repo hosts mainly our statutes. I would argue that there should be an easy way to access and display the contents of our statutes on the web. Since we are not an official UiO organisation, I'd rather it NOT be on the UiO web, but, for example, stay on GitHub. Since the governance repo is a live document, it needs updating and a maintainer. I would argue that it is the duty of the UiO-Carpentry Board to keep the contents up to date and that a Board member should be assigned the task to be active maintainer and implement changes etc.
• the organisational repo has all our community documents. It's mainly used by the local coordinators and other community members and contains info on how we run things here at UiO-Carpentry. It has no website, and I strongly believe that it doesn't need one. I would see it as our "archive" where we keep meeting minutes, reports, workshop how-tos, onboarding documents, but also our logo files, templates, etc. I would strongly advice against moving content out of this repo or using other repos for the same functions (i.e. the governance should not contain meeting minutes etc.).
• StudyGroup is its own thing, but I agree with @Teebusch that it's contents could be incorporated somewhere else, however, the repo has two main functions: (1) List of events and activities, (2) backlog of materials for StudyGroup sessions for reference. How could this be handled smoothly when moving StudyGroup content somewhere else? Also, the studygroup repo was created by @annefou, she should be part of the discussion!

Cheers,

Annika

[Teebusch]

I'm not sure if I understand the suggested ACTION correctly, but I wouldn't disable the uio-carpentry.github.io, just make the separation of concerns clearer and consolidate the 3 github-based websites into one. We could even keep the backlog on uio-carpentry.github.io, but we should tell people who are interested in participating that they should go to the UiO site.

Migrating the study group repo's content into uio-carpentry.github.io smoothly should be possible with a bit of git. Same for the governance docs. Instead of merging the repos into one, we could also load the governance and/or study group repos as a submodule. That way we can keep the documents in separate repos but render all in the same place, i.e. uio-carpentry.github.io

I agree that keeping the organisational repo separate is best and that the org repo doesn't need a website for itself. If we want to render some of the org documents on uio-carpentry.github.io, we can also load the repo as a git submodule. I think the checklists and reports would actually be nice to include on the website. But for starters, we could simply add links.

-- A note on git submodules: Although I believe that this is exactly what they are for, my (limited) experience tells me that working with submodules is a bit painful. So, the fewer submodules, the better. I would prefer to merge the statutes and study group content into the uio-carpentry.github.io repo.

[Teebusch]

@naoe-tatara

2-2, i have been aware, but actually on the event page, the figure is shown. So i have no idea how to fix them. Can anyone help here?

It's a problem with the parentheses in the filename:

Link to image on the course website (works): /english/courses-events/courses/other/Carpentry/images/jekyll_%28software%29_logo.png

Link to image on the workshop list website (doesn't work): /english/courses-events/courses/other/Carpentry/images/jekyll_%2528software%2529_logo.png?vrtx=thumbnail

• %28 %29 are escape charaters for parentheses ( and )
• %25 is escape character for the % (see here)

So it seems like the parentheses in the original image name are being escaped, and then the % in the escape code is escaped again. I don't know how things are connected in Vortex and why the double escaping occurs, but I think an easy fix would be to remove the parentheses from the original image filename...

[arockenberger]

I'm not sure if I understand the suggested ACTION correctly, but I wouldn't disable the uio-carpentry.github.io, just make the separation of concerns clearer and consolidate the 3 github-based websites into one.

OK, if we want to keep the URL, that makes sense!

We could even keep the backlog on uio-carpentry.github.io, but we should tell people who are interested in participating that they should go to the UiO site.

I think it's not important enough info to keep it there. I'd move it into organisational/reporting. One less thing to keep updated in its own repo. Organisational is constantly monitored, so updating is taken care of.

Migrating the study group repo's content into uio-carpentry.github.io smoothly should be possible with a bit of git. Same for the governance docs. Instead of merging the repos into one, we could also load the governance and/or study group repos as a submodule. That way we can keep the documents in separate repos but render all in the same place, i.e. uio-carpentry.github.io

Right, it doesn't need to be all in one repo. However, I think in regards to maintenance, it's easier to have overview over what's going on and what needs updating in one repo than in 2 or more. Might be solved with clear communication and actually assigning repo maintainers; in this case: a website maintainer as well.

I agree that keeping the organisational repo separate is best and that the org repo doesn't need a website for itself. If we want to render some of the org documents on uio-carpentry.github.io, we can also load the repo as a git submodule. I think the checklists and reports would actually be nice to include on the website. But for starters, we could simply add links.

Hm… ok, I see that reports and workshop docs are of a broader interest and thus could be displayed on a website. If this would work with an integration that allows for the material to stay in organisational, I'm all for it! But if it's too much hassle and maintenance, I'd rather have them not displayed, but only linked to.

Best,

A.

[naoe-tatara]

I don't know how things are connected in Vortex and why the double escaping occurs, but I think an easy fix would be to remove the parentheses from the original image filename...

@Teebusch , thank you so much, it worked!!! Yay! Great that I could learn new things today, too 💯

[naoe-tatara]

Thank you for the active discussion on this issue! I edited the title of this issue to avoid some confusions ;)

If the repos can be kept as they are but still we can have one place i.e. https://uio-carpentry.github.io/ to gather things to be published (or at least linked from, to md files such as minutes), I think it is great. Personally I think it is feasible to assign one person for each repo to make the maintenance easier. If necessary, that person can assign someone else to work on things.

[naoe-tatara]

While I agree with @Teebusch on his first comment 1 and 2, I wonder about information duplicates on these places. Indeed we should avoid having same information in different places, while probably it would be nice to have "sufficient" information on the community intro page, hereafter INTRO page under ub.uio to invite other people as well as to make it visible to UB people. Also annual reports should be either separately linked from INTRO page or even PDF files should be archived in Vortex?

But then what is "sufficient" information? I understand that the current INTRO page may be a bit overwhelming and not really "inviting". How can we improve this page? Should we actually keep only

• "Join us" (until "contact") on top (as suggested by Tobias on the last board meeting) with a link to uio-carpentry.github.io for more details,
• "who we are" next in accordion style with A) board members, B) all in org. mailing list, and C) alumni, (of course after getting consent from each, which is on my To-Do list),
• and grey box about the Carpentries at the bottom​?

I personally think the following 2 sections can be left out from INTRO page:

• Vision/Mission Statement -> ATM it is copy and paste from the governance document. To avoid duplicates, we can keep the INTRO page simple to eventually improve the first headlines (in italic, right under the logo) and leave out this section?
• Code of conduct -> I think it is reasonable to have one for workshops under workshop intro page (https://www.ub.uio.no/english/courses-events/courses/other/Carpentry/) and the other under https://uio-carpentry.github.io/ or inside governance document

[Teebusch]

I set up a "proof of concept" Hugo site. You can see it here: https://teebusch.github.io/uio-carpentry.github.io/ (link to repository). It's very rough around the edges and the theme isn't exactly pretty, but...

• It loads the government docs and reports from the org / gov repos (using Hugo modules)
• it renders automatically when changes are made to any of the files in the repo (using Github actions). It won't render automatically when changes are made to the org / gov repos, but there's probably a way to make that automatic, too.
• The study group page has a lot of content. Making it fit the new structure will be a bit of work, so I didn't bother.

[naoe-tatara]

Excellent work, @Teebusch !! Great that it works 💯 I have no idea about Hugo and probably that is why, it was not easy to see how the site was generated. But maybe this is the theme for the next study group session? Anyways, I think this is a great way to integrate everything into one place.

sidenote: probably Carpentry@UiO is not "a part of" UiO, but rather "supported by" UiO/UB? As there are many people who have no official connection to UiO.

[annefou]

That's awesome! I am really very happy to see such improvement. We have done lots of things in the past that probably made sense at that time but are now completely obsolete! Time to move forward!!!!

[Teebusch]

Two important questions: would it be okay for me to ...

1. completely merge the study group page into the github.io page, and eventually archive the study group repo? That would mean study group activity should be tracked in the github.io repo. I will try to make sure no content is lost, of course.
2. strip down the readthedocs governance repo to markdown files, and remove all the "readthedocs" stuff. Actually I would prefer to simply merge the charter and intro into the github.io repo, too, given how little content it is. But I understood that not everyone agrees.

@naoe-tatara

sidenote: probably Carpentry@UiO is not "a part of" UiO, but rather "supported by" UiO/UB? As there are many people who have no official connection to UiO.

Good point. I've fixed it. Generally, I am not keen on doing the editorial work, so I'll leave it up to others to brush up the text once everything is in place. I'm happy to fiddle around with all the web technology stuff, though! :) (And sure, we could make a study group session where we do an intro to Hugo and then a little hackalong, where we fix up the site.)

Also a sidenote: The theme is preliminary. It's important to consolidate all the content first. We can still make it pretty later.

[naoe-tatara]

I agree on the 2 points above. From @annefou 's comment above, I don't think anyone disagree on 1 at least. IMO, if folders are clearly labeled within github.io repo, it should be fine.

And I understand about the text and the theme :)

[annefou]

I agree on both points. I think it is a good way to move forward. Many thanks @Teebusch

[Teebusch]

I've done a bit of work on the redesign of the page now. A lot of little things aren't quite working yet, and the theme isn't very exciting. But I'd be happy to get some feedback. I suggest to handle feedback in the pull request, unless it's "big picture" stuff.

[naoe-tatara]

Thank you for the great works, @Teebusch !! If the workshops are fed automatically, this is fantastic 💯 I went through all the menus shown on the left-hand side one, but will make comments and change-suggestions (like links etc.) later.

Maybe one possibly big picture comment: "email examples" and "post workshop template" could be left out, as they can be actually implemented in Pindena, which only local coordinators need as info and they are not actually used by instructors. In that case, they should not be in the corresponding repo/folder in this GitHub account, either, right?

[lexnederbragt]

As I said at the PR, this is really nice! Thanks @Teebusch. Once we agree to use this design, we could have a small session to go over all text together and submit PR's for improvement. If you haven't noticed, the theme is responsive to my Mac's Light/Dark Appearance setting also!

I'd also appreciate a StudyGroup session on HUGO-based websites...

By the way, I suspect that when you write 'backlog', you mean past workshops, not backlog as things-still-to-be-done...

[Teebusch]

I wonder if it's time to close this issue?

[naoe-tatara]

Absolutely. I will close this.