-- initial import of the OCaml teaching resources page

[yansh]

This is the first import of the wiki page for OCaml teaching resources [1]

[1] https://github.com/ocaml/ocaml.org/wiki/OCAML-Teaching-Resources

[agarwal]

There are a few issues with this pull request:

• Your commit message doesn't match the commit contents. The wiki page you link to contains only a list of courses taught in OCaml, but the new page your propose has much else, and no list of courses.
• Much of the content here is already covered elsewhere on ocaml.org, such as the list of books, installation instructions, and links to exercises. If any of these pages should be modified, it would be great if you can make the change directly to one of these pages.
• Your Tutorials section has several nice links. Can you please add them to the External Links section within the existing tutorials page.
• Your list of Toolkits, IDEs, and VMs are all new. Thanks for gathering these. It's not immediately obvious to me where they should go, but at least it should be under the Learn category. See Incorporate content from awesome-ocaml #502 for a possible solution.

[amirmc]

Thanks for this Yan! A couple of thoughts (and I welcome input from others)

• The page needs to be to be clearly linked to from other pages of the site so that it can be browsed to. My first thought is to add a link in the top paragraph on http://ocaml.org/learn/ and also a link in the tutorials and FAQ section (as the second item). I know that's not strictly accurate but I'm assuming a big overlap between the kind of people who browse those pages.
• I'm generally reluctant to add new URL spaces as each one incrementally makes the site more difficult to navigate and maintain. Our main 'headings' at the moment are learn, docs and community, which each have their own landing page. I see this content fitting under learnas a teaching-resources page but others may feel differently.

[yansh]

• Sorry, I included the wrong link. It should've been https://github.com/ocaml/ocaml.org/wiki/OCAML-Teaching-Resources
• The idea is to create a page for someone who wants to teach OCaml. Still working progress.

[amirmc]

Hi @agarwal! We should have provided some context to this.

There have been requests from people for quickly accessible content where anyone considering teaching OCaml at an institution can find out (a) who else is already teaching the language and (b) what resources exist that can help them create/compose/deliver their own course. In effect, this PR should help towards closing #119

We're aware that some of the content is elsewhere on the site but it's a lot easer to present (and digest) this kind of information if it's collated on one or two pages.

[yansh]

• I think, it is not an obvious place for someone who wants to teach to go to Learn section, that's why I thought a separate page would be better. But if it creates too much an overhead I am happy to move it under Learn
• It might be problematic at this stage, but maybe rethinking the headings to something like Learn -> Teach -> Share will make more sense. Anyway, just a suggestion. This will obviously require much more work.

[agarwal]

Okay, thanks for the clarification. I would suggest making the URL learn/teach.md, although I appreciate learn and teach are opposites. On the other hand, the page is to help people learn about teaching OCaml.

I see the point now, but do you really want to duplicate content. Why not add some prose, explaining the point of the page overall, and link to other pages when the content already exists.

[amirmc]

• Sorry, I included the wrong link. It should've been https://github.com/ocaml/ocaml.org/wiki/OCAML-Teaching-Resources

I've updated the first comment with the corrected URL

[dsheets]

You could also call out teaching resources from the front page.

[dsheets]

repo

[agarwal]

But anyway, I think linking to the books section within this other repo is wrong. Why not link to the books page on ocaml.org.

[amirmc]

I concur. We should refresh our book list and link to that instead.

[amirmc]

Looking through the other book list, I do think it's useful to have additional books on this teaching page that could help educators. For example, the book on Purely Functional Datastructures might be useful but it doesn't belong on the OCaml books page.

The only book we need to add to our books page is the new More OCaml, tracked in #554.

[amirmc]

• I think, it is not an obvious place for someone who wants to teach to go to Learn section, that's why I thought a separate page would be better. But if it creates too much an overhead I am happy to move it under Learn

It's actually not much overhead by itself but if a lot of content ends up in root then overall, it makes it more complicated to maintain the site and keep an understandable structure. That's one reason I moved all the content under headings during the redesign (and coupled them with the header nav).

• It might be problematic at this stage, but maybe rethinking the headings to something like Learn -> Teach -> Share will make more sense. Anyway, just a suggestion. This will obviously require much more work.

I don't understand what you mean here. Can you elaborate?

[yansh]

On 22/10/14 16:36, Amir Chaudhry wrote:

  * I think, it is not an obvious place for someone who wants to
    teach to go to Learn section, that's why I thought a separate
    page would be better. But if it creates too much an overhead I
    am happy to move it under Learn

It's actually not much overhead /by itself/ but if a lot of content
ends up in root then overall, it makes it more complicated to maintain
the site and keep an understandable structure. That one reason I moved
all the content under headings during the redesign (and coupled them
with the header nav).

  * It might be problematic at this stage, but maybe rethinking
    the headings to something like Learn -> Teach -> Share will
    make more sense. Anyway, just a suggestion. This will
    obviously require much more work.

I don't understand what you mean here. Can you elaborate?

This was just a suggestion :) I just thought that something like Learn
-> Teach -> Share (or something similar) will simplify things from the
user/reader point of view. You learn, then you teach it to others and
they create and share the code :) I am not sure Documentation, Packages
and Community is intuitive enough - sounds more like a software project
to me :)

[avsm]

Perhaps "Publish" instead of "Share" would work better?

[yansh]

So how should we proceed?

[agarwal]

Let me propose that the problem is this page isn't intrinsically about teaching resources. All of the items mentioned would fit quite well on other places of the site. So first, do you agree with that? If so, I think my initial suggestions still make sense.

Then, the second issue is what do you want this page to contain? If we split up the content of this page on various other pages, is a single entry point for teaching resources still valuable? What would you write on this page, other than providing links to other pages.

[amirmc]

I would formulate the problem in a different way. Right now there is no simple page that someone wishing to teach OCaml could visit to get a quick overview of what's available and how they might get started (or who else they might reach out to for support). Currently, that individual must pull the content together for themselves by going to many different parts of the site, which a sufficient barrier that they might not bother. From this perspective, a single viewpoint into teaching resources is quite valuable and we can build on it over time.

I think the (quite valid) issue you're getting at is duplication but I would take the chance here and reframe content for a potential educator (and also have internal links to elsewhere). A useful step then would be to get feedback from the kind of people this is aimed at.

[agarwal]

I can certainly see the value of a page that summarizes teaching resources. How about this for concreteness:

• Name this page learn/teach.md.
• Link to this page from learn/index.md.
• As much as possible, try to rewrite the page to link to other existing pages, rather than duplicating the content here. Take into account my initial comments about other places the content could fit. If you think it makes sense, put the content in those other places, but don't let this hold you up. Go ahead and duplicate content if it seems to just make more sense.

[yansh]

On 23/10/14 17:45, Ashish Agarwal wrote:

I can certainly see the value of a page that summarizes teaching
resources. How about this for concreteness:

Name this page |learn/teach.md|.

Link to this page from |learn/index.md|.

As much as possible, try to rewrite the page to link to other
existing pages, rather than duplicating the content here. Take
into account my initial comments about other places the content
could fit. If you think it makes sense, put the content in those
other places, but don't let this hold you up. Go ahead and
duplicate content if it seems to just make more sense.

No worries. Sounds good. Let me try that.

For the record though, as I mentioned before, IMHO having Teach under
Learn is not very intuitive.

[yansh]

On 23/10/14 01:20, Anil Madhavapeddy wrote:

Perhaps "Publish" instead of "Share" would work better?

I chose Share because I was trying to come up with call-to-action for
Community, but I guess Publish works as well.

[carlos-molina]

I was thinking of someone who is interested in learning (not teaching!) OCaml. Can the same page work for both: teaching and learning?

Carlos

[agarwal]

I was thinking of someone who is interested in learning (not teaching!) OCaml. Can the same page work for both: teaching and learning?

:) Well, that supports my claim that there isn't really teaching specific content in the page as it currently stands. Maybe the correct solution is still what was proposed in #502. If anyone cares to comment, please do so there.

[Chris00]

On Thu, 23 Oct 2014 09:45:06 -0700, Ashish Agarwal wrote:

• As much as possible, try to rewrite the page to link to other e
  xisting pages, rather than duplicating the content here. Take into
  account my initial comments about other places the content could fi
  t. If you think it makes sense, put the content in those other plac
  es, but don't let this hold you up. Go ahead and duplicate content
  if it seems to just make more

One way around duplication — if it is deemed important at some point
because pages made of links are not very nice — is to add files with
extension, say, .md.part and include them at the various locations (
mpp should be able to do that).

[agarwal]

Good point. MPP has the input command for this.

[amirmc]

I'm going to close this PR but here's a plan going forward. @yansh is putting together a new page and will submit a separate PR. That page will be under /learn/teaching-ocaml.md (or similar) and have roughly the following structure:

• Intro/overview paragraphs: The page is aimed at those people who might be considering teaching OCaml at their institution (e.g asst profs/lecturers, et al) and this section gives a very brief overview targeted to them.
• List of Universities [1]: A list of school/universities where OCaml is already being taught (as both a record and a form of social proof).
• List of resources [2]: Summary of resources available and links off to elsewhere on the site or specific content being pulled in as appropriate
• Map of institutions: https://www.google.com/maps/d/view?mid=zk8_K4G_usic.kkzYvEvqV44Q

[1] https://github.com/ocaml/ocaml.org/wiki/OCaml-at-School
[2] https://github.com/ocaml/ocaml.org/wiki/OCAML-Teaching-Resources

[yansh]

@agarwal Quick question. Do you know how to import part of the page into another pager. The idea is to avoid duplication. So if there is Exercises section available, I'll pull into the Teaching page.

[agarwal]

@yansh MPP has an input command, which lets you import a file. However, I've lost track of what compilation tool chain we're using, so can't recall when MPP is being invoked. I unfortunately don't have time to look into this now, perhaps I can check more next week.

[pw374]

The part of the page that is shared should be in a separate file, which you may simply include with something like

((! input path/to/the/file/to/input !))

Snippets are generally in https://github.com/ocaml/ocaml.org/tree/master/template

Example: https://github.com/ocaml/ocaml.org/blob/master/site/index.md

[yansh]

Awesome thanks! @agarwal @pw374