Beginner and Advanced are kind of weird ways to catagorize the tutorials

[SteveBronder]

We could separate it by task type. So we have a header at the top for regression, classification, clustering, survival, (hopefully forecasting soon), etc. and the sub tutorial things associated with each. Then we have other headers like preprocessing, resampling, imputation, etc.

Even for functions like makeLearner there are specific things you would do for a classification learner but not for a regression learner. Separating all that lets us talk about both of those in a non-congested way.

Something like scikit-learn http://scikit-learn.org/stable/

[berndbischl]

We could separate it by task type. So we have a header at the top for regression, classification, clustering, survival, (hopefully forecasting soon), etc. and the sub tutorial things associated with each. Then we have other headers like preprocessing, resampling, imputation, etc.

that does not work that well. maybe for some sub sections. but you dont want to write tuning 5 times, for each task type. the same holds for MANY other sections of the tutorial. and thats IMHO an advantage of the mlr structure. that its always handled in the same manner.

for some intro parts / quickstarts / use cases you might be correct though.

[SteveBronder]

Breaking it up by task type is one suggestion. I fear that eventually 'Advanced' is going to slowly creep to be the length of my computer screen.

What would be a meaningful grouping?

[berndbischl]

Breaking it up by task type is one suggestion. I fear that eventually 'Advanced' is going to slowly creep to be the length of my computer screen.

thats certainly true. potential breakup:

• tuning (or model optimization, including feature selection and others)
• other tasks / advanced tasks (like multi label)
• evaluation
• visualization

?

[schiffner]

Hi,

I agree that Advanced is getting very long and that rather than Basics and Advanced we could have more specific titles. (We started a similar discussion in #6. There are some more thoughts and suggestions but we did not come to a conclusion.)

I guess because I know the contents of the tutorial best I can try to come up with an initial suggestion how to categorize it in a better way and we can discuss it here.

From a technical point of view:

• We could certainly add some more categories but not too many to the upper horizontal navigation bar. I was planning on adding a category "Use cases / Worked examples" once the use cases are merged.
• It is possible to add more levels of navigation to the menus (like Advanced). In #6 there are links to screen shots how this would look like. I personally am not sure if this makes it easier on the reader, but don't have a strong opinion on this.

[masongallo]

We can also take a look at how caret split things up: https://topepo.github.io/caret/

[schiffner]

More inspiration: http://scikit-learn.org/stable/documentation.html

[SteveBronder]

^ I like how scikit learn uses the top header.

scikit has a really nice template for their documentation. In particular I like the homepage and how it breaks out everything. I think we are not using that real estate as well as we could (plus putting everything on the home page would let us break things up more). I don't like it as much, but the Eigen C++ library also has a nice template, though very different from ours https://eigen.tuxfamily.org/dox/

[schiffner]

Sorry, I'm dumb, overlooked that you linked scikit-learn already. :woman_facepalming:

So we have two different topics:

1. Improve the structure of the tutorial
2. Have a homepage where one finds everything in one place

Re 1.

• We need a better chapter/section/subsection structure.
• We need a template that better conveys the structure (maybe with a sidebar that shows chapter/section names with numbers). If we want to keep mkdocs for building the html we could look at other themes.
  • We have a bootswatch kind of theme. mkdocs also supports a bootstrap theme (http://mkdocs.github.io/mkdocs-bootstrap/) which looks a little bit more like the scikit-learn homepage. (I'm not sure yet what one can show in the sidebar).
  • One can also use the ReadtheDocs theme with mkdocs (http://www.mkdocs.org/user-guide/styling-your-docs/#built-in-themes). In my opinion our current theme is prettier, but ReadtheDocs has a clearer structure. (In order to use all features of ReadtheDocs (like versioning or pdf creation) one has to use Sphinx instead of mkdocs though.)
  • The scikit-learn guys seem to use Sphinx.

Re 2: We kind of have this (http://mlr-org.github.io). At the moment is mainly hosts the blog and has links to the tutorial and other stuff. One certainly could use this in a better way, i.e. collect more info in one place, connect the stuff we have more closely.

[pat-s]

This issue was moved to mlr-org/mlr#2309