The README should have more columns and be human-written

[dkmiller]

It would be better to add more columns to tables in README.md for easier navigation. For example, we can add the following columns:

ML framework: TF, PyTorch, LightGBM, etc.

Dataset: MNIST, Iris, etc.

Distributed or single machine

Currently README.md is automatically generated by code. Is that a good idea?

We need better organizing Tutorial notebooks. As of 11/3, the order of those notebooks looks random.

the readme.py script also generates stuff other than the README, e.g. build definitions. We should explore ways of making all the code in this repo "human written" (e.g., populate matrix values via some script?).

[lostmygithubaccount]

disagree on the human-written, it is not maintainable/scalable. There are human-written portions, in which I think we could provide a few "getting started? try these first" pointers. But over time I expect the examples to be 100+ and it will not be maintainable to have all of them in the README unless it's automated. We do want all of them indexed in the README.

For the more rows: it was like this, and I found it ugly to look at. Instead, I simplified it to what I thought were the important columns, with any additional information being placed in the description.

The order of files in the README is sorted by name per table.

[dkmiller]

Probably worth having, at a minimum, a human-curated "snippet" at the top of the README, even if the rest isn't.

There's no relevance / keyword search (only browser-based, text match). Can also search in the repo.

Worth thinking through user experience to find specific examples in a very long README.

Follow up offline: perhaps we can automate "PR against PR" to fix the README.

[lostmygithubaccount]

here is what the README used to be with more columns: https://github.com/lostmygithubaccount/azureml-examples

[dkmiller]

@lostmygithubaccount I actually think that is easier to navigate.

@dongwookim80 what are your thoughts?

[lostmygithubaccount]

in #342 I have gone the opposite direction - this would be a good issue for someone to take up :)

[lostmygithubaccount]

closing this issue. we are using this repository as the central location for examples, and will work within docs & the studio to ensure the best examples are prominent rather than maintaining in the README