Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Put pre-hackweek materials on Wiki #74

Closed
leewujung opened this issue Jul 27, 2020 · 13 comments
Closed

Put pre-hackweek materials on Wiki #74

leewujung opened this issue Jul 27, 2020 · 13 comments

Comments

@leewujung
Copy link
Member

Follow-up from #73 :

I think we should just remove/archive the Wiki completely and host the same set of materials like what's done in ICESat-2 hackweek. I don't think Wiki makes sense in our context.

We would have to spin up the pre-hackweek materials relatively quickly.

I don't think it matters what we use, as long as we can do it quickly. I've set up docs using Sphinx but not MkDocs. A quick alternative is simply putting materials on a new page on our website. The downside of doing this that each page gets longer and there's no easy index of sections like in the docs setup.

@ocefpaf @emiliom : let's decide which path to go ASAP. I can help move the materials once the destination is setup, since I am pretty familiar with where things were on ohw19 wiki. We should definitely ask @asx- 's help to review and potentially update materials once they are transferred.

@ocefpaf
Copy link
Member

ocefpaf commented Jul 27, 2020

Pinging @leportella who may help us with the pre-hackweek. She has a repo with the basics already, maybe let's just link to it for now.

@emiliom
Copy link
Member

emiliom commented Jul 28, 2020

My recommendation is to base the wiki replacement on the MkDocs template used on ICESat-2 Hackweek and also in WaterHackweek.

I'm very familiar with this structure at this point, based on an initial attempt at developing a common structure and possibly common resources that could be of use to both OHW and WHW: https://emiliom.github.io/hackweek-preliminary-tutorials/

I could create a repo with this template right away on Tuesday. It's pretty easy to edit, as it's based primarily on Markdown documents and a simple configuration. Plus I'll provide the instructions.

From there, we can link to @leportella's repo as needed; I imagine that would take the form of links to individual sections of her materials?

@emiliom
Copy link
Member

emiliom commented Jul 28, 2020

@leewujung and @ocefpaf any thoughts? I should go forward and create a new repo with the Mkdocs site?

One thing I forgot to comment on was the label (and site/repo name) "Learning Resources". That's what WHW and ICESat-2 HW have used. I'm not entirely sold on that label, but I don't have a better suggestion. Do you?

@ocefpaf
Copy link
Member

ocefpaf commented Jul 28, 2020

@leewujung and @ocefpaf any thoughts? I should go forward and create a new repo with the Mkdocs site?

Sure. Let's just avoid putting a year on the repo name. We can either make a rolling resource or a branch for each year. (I prefer the former.)

One thing I forgot to comment on was the label (and site/repo name) "Learning Resources". That's what WHW and ICESat-2 HW have used. I'm not entirely sold on that label, but I don't have a better suggestion. Do you?

Consistency would be nice but I prefer "pre-hackweek" instead of "learning resources." It is all learning resources after all.

@emiliom
Copy link
Member

emiliom commented Jul 28, 2020

Let's just avoid putting a year on the repo name

Absolutely!

Consistency would be nice but I prefer "pre-hackweek" instead of "learning resources." It is all learning resources after all.

Depending on what we want to do with it, it's not exclusively pre-hackweek stuff.

@leewujung
Copy link
Member Author

Consistency would be nice but I prefer "pre-hackweek" instead of "learning resources." It is all learning resources after all.

Depending on what we want to do with it, it's not exclusively pre-hackweek stuff.

Can we focus on getting pre-hackweek materials up now in a doc FOR OHW20?
We're limited on time, so it'll be the best to not get this mingled with updating other materials from the website -- to avoid duplication so that participants can find things easily in one place.

We can work on changing what goes where later. Personally I'd love to completely ditch the clunky jekyll website and use simple doc formats. It is much easier to maintain and find information.

@emiliom
Copy link
Member

emiliom commented Jul 28, 2020

Not sure if that's a yes on the mkdocs site or something else. What do you mean by "simple doc formats"? A series of plain markdown files on github?

I can deploy this thing right now. The individual docs are markdown, so maintaining them will be simple. Like Jekyll, it is still a site that needs to be "built", though. Think of it as a lighweight and markdown-based version of jekyll or sphinx.

@emiliom
Copy link
Member

emiliom commented Jul 28, 2020

... and I'm on board with moving forward right now.

@leewujung
Copy link
Member Author

Not sure if that's a yes on the mkdocs site or something else. What do you mean by "simple doc formats"? A series of plain markdown files on github?

Simple doc format = formats based on MkDocs, Sphinx, or anything similar.

If you can spin up MkDocs that'll be great. If you or someone could set up github action to do the building that will be nice, but if not we can also use RTD in the short time frame before OHW20 and move afterwards. It's not hard to do since we just need to change the target from the OHW website.

@emiliom
Copy link
Member

emiliom commented Jul 28, 2020

I'm working on it now (already created a blank repo). Will report back when it's ready

@emiliom
Copy link
Member

emiliom commented Jul 28, 2020

Done: https://oceanhackweek.github.io/ohw-learning-resources/, https://github.com/oceanhackweek/ohw-learning-resources

We can organize it any way we want, but I suggest we learn from https://icesat-2hackweek.github.io/learning-resources/. I can lead the overall coordination and management.

GitHub Action for auto-build is not set yet, but until it is, I'll take responsibility for manually building the site (gh-pages). @ocefpaf, do you think you can help me with setting it up (I found this guidance)? If not, I think it'll be good for me to learn how to set up a GitHub Action. FYI, I asked the ICESat-2 Hackweek crew how they were building it, and they said they didn't have an auto-build and were making do through a manual, coordinated process.

We can have a zoom call for initial coordination if you'd like.

@emiliom
Copy link
Member

emiliom commented Jul 28, 2020

I'll be tracking the build automation issue at oceanhackweek/ohw-resources#2

@leewujung
Copy link
Member Author

Looks like everything is addressed under this issue. I'll close this now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants