Outdated examples

[jebej]

Some examples, like the first one for SDEs, seem to be outdated and currently do not work. The equivalent SDE example on the manual is here and does work.

I suggest to get rid of the notebook tutorials, it will be easier to manage only one set of examples.

[ChrisRackauckas]

I just pushed an updated version for the SDEs. Thanks for notifying me.

I suggest to get rid of the notebook tutorials, it will be easier to manage only one set of examples.

I like having this setup of extra tutorials to show people how to do a bunch of cool stuff, and just need to fill it up with more content (like Hybrid differential equations, showing how to use cool types, etc.). I think that should all be distinct from the manual, which is mostly about documenting what's available. However, the introduction notebooks and the introduction tutorials in the manual have become about the same thing, so yes it may make sense to delete those notebooks.

[jebej]

Thanks.

Regarding the second point: another reason why I was suggesting removing the notebooks is that trying to understand what is "JuliaDiffEq" is a bit overwhelming for newcomers. There are a bunch of repositories named "something DiffEq" or "DiffEq something" and it is (initially, and to me at least) unclear what to use/where to look.

Having only one centralized resource for documentation would help the situation a bit.
That's just the feeling I got as I started looking into this, others might disagree.

In any case, thanks for these, like I said on Discourse, I find the quality in general to be really high!

[ChrisRackauckas]

Yes, finding the repositories can be a little overwhelming. My main goal is actually to make the tutorials button in the documentation eventually just go to DiffEqTutorials.jl. That way from the documentation it's easy to find all of the tutorials, keeping them distinct but much easier to find.

Sadly, you can't do that with Documenter.jl. I opened an issue awhile ago for that:

JuliaDocs/Documenter.jl#344

Maybe there's still a better way to do this.

[ChrisRackauckas]

I deleted the introduction examples as they are simply outdated repeats from the manual introductions.

Regarding the second point: another reason why I was suggesting removing the notebooks is that trying to understand what is "JuliaDiffEq" is a bit overwhelming for newcomers. There are a bunch of repositories named "something DiffEq" or "DiffEq something" and it is (initially, and to me at least) unclear what to use/where to look.

I hope this page of the website clears this up: https://juliadiffeq.github.io/packages.html

Having only one centralized resource for documentation would help the situation a bit.
That's just the feeling I got as I started looking into this, others might disagree.

I agree that a centralized documentation helps, but I also think that splitting separate ideas can make things far less convoluted. The DifferentialEquations.jl documentation is made to be the centralized documentation, and it covers how to use the functionality in all of the related repositories. However, the JuliaDiffEq organization details (what is in the different repositories? How do I contribute?) are separate issues, and so they are covered by the organization website, and a developer documentation.

The tutorials I think should be thought of as a sprinkle of something extra. The documentation is supposed to be written so that way they are not needed (and if there is something that is missing, please file an issue). However, some people learn better by having an example show step by step how to do something. For example, solving a specific PDE: how do you interpret that equation, adjust it to the package, and animate the solution? All of these are technically in the manual, but seeing them as one stream of thought can make it easier to digest. So the tutorials do serve a very different purpose.

That said, there shouldn't be overlap, and some sections of the documentation should be "less tutorial-y". I am going to keep the introduction tutorials in the documentation since I think there's no better way to introduce a package to someone, but I deleted the repeated introductions from this repository. Then other sections of the documentation which were written more of as tutorials (parameter estimation), should be re-written to be more of a manual + one simple example, and point here for more detailed examples. That way the manual is kept clean, but this can be expanded with all sorts of "how to" answers for users who like this format to explore (but kept totally optional).

That said, the actionable part of this issue has been dealt with, so I am closing the issue. If you want to discuss the overarching design and philosophy of this decision some more, please feel free to open another issue.