Structure/grouping of the tutorial

[pat-s]

From @SteveBronder on March 11, 2017 2:23

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/

Copied from original issue: mlr-archive/mlr-tutorial#97

[pat-s]

From @berndbischl on March 11, 2017 10:39

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.

[pat-s]

From @SteveBronder on March 11, 2017 16:40

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?

[pat-s]

From @berndbischl on March 11, 2017 20:36

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

?

[pat-s]

From @schiffner on April 4, 2017 12:42

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 Add over / undersampling wrapper to mlr #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.

[pat-s]

From @masongallo on April 4, 2017 14:4

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

[pat-s]

From @schiffner on April 4, 2017 14:15

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

[pat-s]

From @SteveBronder on April 4, 2017 16:50

^ 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/

[pat-s]

From @schiffner on April 10, 2017 10:19

Sorry, I'm dumb, overlooked that you linked scikit-learn already. 🤦‍♀️

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]

Possible structure:

• Preprocessing (Preprocessing, Tasks)
• Tuning, Training (incl. parallelization, feature sel, etc)
• Evaluation & Visualization
• Special Applications (Survival, Spatial, Clustering, Cost-sens etc)
• Docs (including createLearner, Integrated Stuff, NEWS
• mlrExtensions (links to all other mlr packages)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.