SEO and usability: Make release tutorial the default

[jakob-r]

To improve usability I would like to let http://mlr-org.github.io/mlr-tutorial/ directly link to the release version of the tutorial. At the same time http://mlr-org.github.io/mlr-tutorial/release/html/ and http://mlr-org.github.io/mlr-tutorial/devel/html/ would live on. To link to the devel version of the tutorial I would simply add a link on the "home" Page of the Tutorial. Furthermore I suggest to add a link to the Blog. At the moment we are at Position 11 for "machine learning r tutorial". We have to get to page 1 on google!

Opinions?

[larskotthoff]

Sounds good.

[SteveBronder]

Good yes!

[jakob-r]

I am hesitating. For example we missed to build a 2.11 release tutorial and I can imagine unless we can automatize this process via Travis that the devel version of the tutorial is more up 2 date to the cran version than the release version. Also the timeline usually looks like this:

PR in mlr --> merge --> cran release
     Work on tutorial page --> PR --> merge

So if we just merge stuff that is in the CRAN version of mlr we don't need a devel version anymore.

[berndbischl]

how about we only maintain one version of the tutorial from now on.

if there are slight discrepancies between cran and devel version, so be it. and we mainly talk bout not so totally new stuff in the tutorial?

and i think we can very well live with stuff like: a) BB merges new forecasting stuff from @Stevo15025 into master on GH b) new mlr not yet on cran c) @Stevo15025 already posts a nice page in the tutorial

what do you think?

[larskotthoff]

Haven't we always done that? The tutorials for the releases are really just frozen versions, they're not maintained. The advantage is that if somebody for whatever reason needs to work with an old version of mlr, they can still see the tutorial for that.

[berndbischl]

Haven't we always done that? The tutorials for the releases are really just frozen versions, they're not maintained. The advantage is that if somebody for whatever reason needs to work with an old version of mlr, they can still see the tutorial for that.

yeah, but it does create some burden on us. and makes it a bit more confusing to readers. if you want proof, i present exhibit A: this thread. and exhibit B: we forgot to create a version. and exhibit C: julia needs to do something each time i release to cran.

[larskotthoff]

A: Not sure what you mean. It's about improving the linking? B and C: Make creating a new version part of the release process that the person who makes the release takes care of.

[berndbischl]

A: Not sure what you mean. It's about improving the linking?

which we would not need, i mean the discussion how to do that, if there would be 1 tutorial and not 2.

B and C: Make creating a new version part of the release process that the person who makes the release takes care of.

great idea. thats me. what other issues should i disregard in order to add that to my todo list?

[berndbischl]

the point is: the less we have to do, and the more naturally the whole process is, the better for us. we already have waaaay too many checklist, standards, things to keep in mind. i am not saying those are all bad, and i dont want a meta discussion.

but here, i see the option to cut away some fat. and i dont really see the downside to this.

its like this: the tutorial CONTENTS are in dire need of improvement. having a backlog of all versions, and a devel and release version, is maybe not the most important point?

just thoughts, if people disagree we can stay with what we have.

[larskotthoff]

Making a tutorial "release" involves copying a directory and committing the result, and of course we could have a script to do this as well. It's a very small amount of effort.

[berndbischl]

then how do you resolve the problem that @jakob-r raised here?

[berndbischl]

that exactly what i meant, i mean this type of problem. jakob suggested to link to the release version. then he got some doubts. possibly with reason.

i, for example, never click on the release version of the tutorial. i always go to "devel". EDIT: and refer external people to it. why: because many more fixes will the in there. that outweighs that maybe the user sees a function which is not yet on cran.

this type of "confusion" i would like to remove....

[SteveBronder]

A lot of this seems to be resolved by adding something like this to the PR guidelines

- If your branch adds new functionality you must create a branch in the mlr tutorial
    explaining the new addition. Include a rawgit link in the first comment of the PR

This has two levels of good

1. This

   PR in mlr --> merge --> cran release
    Work on tutorial page --> PR --> merge

Becomes

Make Branch ------------> PR --> merge --> cran release
Work on tutorial page --> PR --> merge^

2. Reviewers get a clear overview of what a branch adds and how it should work

Then we can just have one version

[jakob-r]

I think I will try to write a script that creates the new folder automatically once the mlr version increases. Apart from that I would stick to make the devel version the default.

[jakob-r]

Okay. Build file is updated. The state is now.

• We always build into devel
• Folder with github version number is a symlink to devel
• If the github mlr version does not match the folder that symlinks to devel the skript copies the contents of devel to the directory that was formerly symlinked to devel. Furthermore it creates a new symlink with the actual gitub version number that links to devel
• Stuff is build into devel

We now also take care of the pdf. It also goes automatically into the right version / devel subdirectories. For compatibility the mlr-tutorial.pdf in the root is symlinked to the devel pdf.