Revamp tutorials page

[bobbypriam]

Page in question: http://ocaml.org/learn/tutorials/

At this point, the tutorials linked from this page is a bit of a mess. For example, there are "Maps", "Sets", and "Hash Tables" on the left side, and inside "Standard Library Examples" on the right side contains only links those three. There are also "Compiling OCaml Projects" and "Filenames and Extensions" which seems like basic knowledge but put near the end of the list, below even formatting texts, objects, and garbage collection. On that note, it is also unclear of whether or not those tutorials are meant to be read in sequence.

My suggestions, therefore, are to:

1. Group those tutorials under relevant distinct categories. For example: Getting started, standard library, build systems, C interop, common tasks, etc.
2. Come up with a reasonable ordering of those tutorials.
3. Come up with a contributing guide for the tutorials.

Related to number 3, it is also better if we make it clear what kind of content we're expecting. For example, what about articles related to OCaml deployment, e.g. with Docker or Heroku? Building static binaries? What are the criteria of a topic that decides whether it can be included? For example, if we have a guideline for writing documentation, would it make sense to put it under tutorials?

Also, what about great tutorials written in external blogs? I assume it can be put on the "Tutorials on OCaml" under "External Links". Are people encouraged to put their own articles there?

There is also the issue with attribution: the benefit of writing a tutorial in your own blog is that you can have your name attached to it (which serves as your own portfolio). Why should we write tutorials on ocaml.org instead of our own blogs?

I think I can try tackle thinking about some of this, just want to put this out first to get everyone's opinion.

[bluddy]

I think it makes the most sense to have both: start with the link to the tutorial, and then follow up with including the content.

However, I don't know what to do about out of date or irrelevant tutorials. Can we scrap them? Do people have the expectation that their contribution will stay on ocaml.org forever?

[agarwal]

I don't know what to do about out of date or irrelevant tutorials. Can we scrap them?

How about putting them under a section titled "Out of Date" or "Archive" or something similar.

[Chris00]

I agree with @agarwal that leaving them in a “Obsolete” section would be better. In addition, each of these “out of date” tutorials should mention at the beginning what is the now better way of doing the same (e.g. camlp4 → ppx) with a link to the new technology so that people who find them from, say, a web search are redirected to the up-to-date information.

[Chris00]

Also, what about great tutorials written in external blogs?

IMHO, we should ask the author the permission to reproduce it on o.o — with a link to the original version. Indeed, the post may disappear from one day to the next. When porting the content of the ocaml-wiki at the beginning of o.o, we had to literally dig into the archives of that site which was no longer up.

There is also the issue with attribution: the benefit of writing a tutorial in your own blog is that you can have your name attached to it (which serves as your own portfolio). Why should we write tutorials on ocaml.org instead of our own blogs?

It needs not to be exclusive. People can publish blog posts and we can copy to the tutorial section those which are particularly beneficial for the community. The benefit for the author is recognition by the community and a link can be added to the original blog post.

[agarwal]

we should ask the author the permission to reproduce it on o.o — with a link to the original version

I think this is overkill. It's extra work, and now there are 2 copies of the same material on the internet. It's true that external links might die, but hey, that's the nature of the web. We have to live with it. Perhaps a web page dying is a sign it's not useful anymore anyway.

Why should we write tutorials on ocaml.org instead of our own blogs?

IMO this is just a personal choice. Having personal blogs about OCaml is great. But some content clearly makes sense on ocaml.org and perhaps you're motivated to thus put it on ocaml.org. That's great too.