Docs restructure #810
Docs restructure #810
Conversation
| ] | ||
| ], | ||
| "Model simulation" => Any[ |
There was a problem hiding this comment.
Maybe calls this “Simulating Dynamics” to contrast with Steady-State analysis and make clear this is about temporal simulation?
There was a problem hiding this comment.
Kind of makes sense, just feel "Model simulation" is very clear what it means, and it is something basic enough that it is not too surprising that it occur in different settings (e.g. spatial simulations)
There was a problem hiding this comment.
But calculating steady-states is also model simulation so it is weird to put it in a different category…
There was a problem hiding this comment.
If you want to move it into “model simulation” as a sub-folder then that would be another way to address this.
There was a problem hiding this comment.
But model simulation is part of most other categories as well? E.g. the spatial modelling is basically just specific types of simulations.
Given that we have a specific category for finding steady states, it makes sense to have the simulation-based approach for that there as opposed to separating it from e.g. HC and nonlinear-based approaches.
If you have a better name for this section I am happy to change it, but “Simulating Dynamics” sounds weirdly convoluted to me.
There was a problem hiding this comment.
You could also then call it well-mixed model simulation to distinguish from spatial model simulation.
There was a problem hiding this comment.
Right, but then we have Bifurcation analysis and finding steady states through homotopy continuation as a sub-category to model simulations? Does that really make sense?
I don't see any reason we would want to have a different categorisation than the current one. I am happy to hear arguments, but I don't think that is what we are discussing. I.e. there is one discussion on how to categorise tutorials in groups with related stuff, and then there is the question of what names for the various tutorials and group makes sense. If I understand it right we are discussing the second part?
Regarding the names, I think it makes sense that you have a "Simulation" category which covers how simulation works. Since CRN modelling is pretty much about simulations, it is natural that other categories involves it (i.e. steady state simulations, spatial simulations, simulations to solve the inverse problem). Then stuff which is discussed in the simulation section is naturally relevant to these. In this sense I think it makes sense to have a simulation section, and it is not weird that spatial simulations are covered in the spatial modelling section (which also includes how to create spatial models, which is distinct from the model creation sections).
If we want to be precise we would probably have to call it "Forward non-steady state simulations of well-mixed systems" (or towards that), but that would only be weird. I don't see how "Simulation Dynamics" really make anything better or clearer. "Simulation Basics" could work, but I wouldn't really can stuff in there basics.
There was a problem hiding this comment.
If you think the current categorisation is non-intuitive, I am happy to discuss alternatives. If not, I think we should move toward discussing category names (and if we cannot come up with good names within the next day, we should just use some alternative, raise an issue, and continue the discussion in parallel as we work towards v14).
There was a problem hiding this comment.
Right, but then we have Bifurcation analysis and finding steady states through homotopy continuation as a sub-category to model simulations? Does that really make sense?
Yes it does.
Perhaps the organization should be focused on the mathematical model one is working with instead. In that case a splitting like ODE Models (which includes SS analysis as a sub-category as it is currently only about ODE models), and Stochastic Models makes more sense. The latter can include SDE/jumps along with ensemble problems and stats calculations. We can potentially split Stochastic Models in the future if there is a enough material to warrant separate jump/SDE categories.
The benefit to this is I suspect most users are just interested in ODE models, and so everything they might want to do with regard to solving such models would be collected together sequentially.
There was a problem hiding this comment.
I def. think there is a point, however, I do not really agree. Stuff like simulation structure interfacing and plotting are common to all categories. Looking at the ways to do it, I think that I have proposed here feels most intuitive.
Practically, whenever I try to work around what you are suggesting to an actual structure, things become weird. How do you actually propose to sort the new docs?
|
Sorry as I know this will annoy you, but I no longer think it is a good idea to append numbers to the folders or tutorials. The reason being that if we at any point decide to reorder things again and/or insert a new tutorial/folder we will then have to rename every subsequent folder/file, along with having to update any links to a file that has been renamed. For this reason I don't think we should use this number-based scheme for ordering things within the filesystem. |
|
The links issue is also important, as we may link directly to a tutorial via Zulip/Slack/Discourse and it would be good to ensure the link doesn't then change in the future if possible. But using a number-based scheme it seems quite likely that we could change the numbering and hence break links. |
|
I went and looked at several packages people say have good docs like DynamicalSystems.jl, Agents.jl, and DifferentialEquations.jl and none of them seem to use a numbering scheme for file/folder names. I think this is likely due to the issues I mention above. |
|
That is a good point. As mentioned, I don't mind removing internal numbering. However, I do think the folder ones is genuinely useful. I have spent (and will likely continue spending) lots of times going through Catalyst docs, and I always found the weird ordering annoying. |
|
I feel strongly that all numbering has to be removed, including for folders, otherwise we will still break links when we inevitably renumber folders due to moving things around or introducing new folders (for example, for hybrid models eventually). I'm fine with keeping the current organization if we just change "Model Simulation" to something less generic that makes clear that section is only about specific types of simulation. I don't know what a good name is that you will approve of, and am tired of bikeshedding it, so please just propose something else you are comfortable with that is more concrete/specific to what that section is actually covering. Copasi uses "Time course simulation" FWIW. |
This revamps the structure of the docs. It depends on the equation pr, hence lots of changes are marked.
Pretty much it sets up the documentation as outlined in the plan. The idea is when I add PRs for the new doc pages, I will just fill in the lines where I have marked them. That way, all further doc changes is entirely orthogonal to each other (except for reference between them).
I have also renamed the various folders to have e.g. "02_" prepended. That way they appear in the same order in the documentation and in the file system. I have done the same for both the doc files and the folders. Right now, I do not feel super strong about having these prepended numbers to the actual files, but I'd like to try it out. For the folders I am really keen. I have written loads of docs the last 6 months, and it is really annoying to have them sorted randomly.