search

TuringLang / docs

Documentation and tutorials for the Turing language
https://turinglang.org/docs/
MIT License
229 stars 99 forks source link

Reordering the tutorials? #270

Open ParadaCarleton opened 3 years ago

ParadaCarleton commented 3 years ago

Looking at the tutorials, the ordering looks a bit random. Perhaps we should reorder the tutorials, roughly in order from least to most advanced, to make it easier to understand them? I'd suggest something like:

  1. Introduction
  2. Linear regression
  3. Logistic regression
  4. Multinomial regression
  5. Poisson regression
  6. Gaussian mixture model
  7. Infinite mixture model
  8. Variational inference
  9. Bayesian neural networks
  10. Bayesian differential equations
  11. Hidden Markov models

So the order goes from easy to difficult; this order also keeps generalized models together with their more specific instances (e.g. logistic regression is followed by multinomial regression).

I can make the PR if you guys are interested.

cpfiffer commented 3 years ago

Yep, I like that ordering. Currently they're just organized in the order that they were written, which is not super great as you've noted.

The big issue here is that moving everything around will break all the old links to these tutorials, which isn't super great. I'm kind of tilting towards not rearranging them for just that reason, but I'm very open to being persuaded.

ParadaCarleton commented 3 years ago

Yep, I like that ordering. Currently they're just organized in the order that they were written, which is not super great as you've noted.

The big issue here is that moving everything around will break all the old links to these tutorials, which isn't super great. I'm kind of tilting towards not rearranging them for just that reason, but I'm very open to being persuaded.

Perhaps we could redirect the old links to the new links, and remove the numbers from the link so this won't be a problem in the future?

cpfiffer commented 3 years ago

Sure, why not? I'm open to a PR.

ParadaCarleton commented 3 years ago

Sure, why not? I'm open to a PR.

Cool, I'll make a PR here; do you know who usually handles the JS and such for the website and could get a redirect link working? I don't know how to do web dev.

rikhuijzer commented 3 years ago

Cool, I'll make a PR here; do you know who usually handles the JS and such for the website and could get a redirect link working?

You need to figure out how people do it in Franklin.jl. Redirects are a native HTML construct, by the way, not Javascript per se.

rikhuijzer commented 3 years ago

Oh sorry. Turing isn’t using Franklin. Then, just place the correct redirect files at the right places, I guess

ParadaCarleton commented 3 years ago

Oh sorry. Turing isn’t using Franklin. Then, just place the correct redirect files at the right places, I guess

What would those places be?

KronosTheLate commented 2 years ago

Big +1 on reordering the tutorials - as a newcomer, the current order is indeed confusing. Worse than that, it starts with subjects that sound daunting to me, killing the "let's start at the beginning and learn this stuff!" feeling/motivation right away.

yebai commented 4 months ago

@shravanngoswamii do you want to give this a go?

shravanngoswamii commented 4 months ago

@yebai It just need updating _quarto.yml, Is it fine to rename them as you were saying no to restructure the file organization previously?

I can either rename the files and update _quarto.yml or else reorganize whole file structure of docs like this: All this in docs repo, using-turing, tutorials, contributing & for-developers folders in root directory: ├───using-turing │ ├───getting-started │ ├───more... ├───for-developers │ ├───abstractmcmc-turing │ ├───more... ├───tutorials │ ├───bayesian-differential-equations │ ├───more... ├───contributing │ ├───contributing-guide │ └───contributing-style-guide

yebai commented 4 months ago

More consideration is required to reorganise the docs; let’s reorder them for now.

shravanngoswamii commented 4 months ago

by renumbering and updating quarto.yml, If I am right?

yebai commented 4 months ago

That’s correct.

shravanngoswamii commented 4 months ago

  1. Introduction

  2. Linear regression

  3. Logistic regression

  4. Multinomial regression

  5. Poisson regression

  6. Gaussian mixture model

  7. Infinite mixture model

  8. Variational inference

  9. Bayesian neural networks

  10. Bayesian differential equations

  11. Hidden Markov models

Is this sequence correct? and what about these:

and also get-started/using-turing section's sequence is correct? also for developers section!