Update, proofread and crosscheck docs for first release

README.md

@@ -6,23 +6,22 @@
 [![codecov](https://codecov.io/gh/JuliaDynamics/ProcessBasedModelling.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/JuliaDynamics/ProcessBasedModelling.jl)
 [![Package Downloads](https://shields.io/endpoint?url=https://pkgs.genieframework.com/api/v1/badge/ProcessBasedModelling)](https://pkgs.genieframework.com?packages=ProcessBasedModelling)
 
-ProcessBasedModelling.jl is an extension to [ModelingToolkit.jl](https://docs.sciml.ai/ModelingToolkit/stable/) (MTK).
-It is an alternative framework to MTK's
-native component-based modelling, but, instead of components, there are "processes".
-This modelling approach is useful in the modelling of physical/biological/whatever systems, where each variable corresponds to particular physical concept or observable and there are few (or any) duplicate variables to make the definition of MTK "factories" worthwhile.
-In many modelling scenarios this follows the line of reasoning in the researcher's head.
+ProcessBasedModelling.jl is an extension to [ModelingToolkit.jl](https://docs.sciml.ai/ModelingToolkit/stable/) (MTK) for building a model of equations using symbolic expressions.
+It is an alternative framework to MTK's [native component-based modelling](https://docs.sciml.ai/ModelingToolkit/stable/tutorials/acausal_components/), but, instead of components, there are "processes".
+This approach is useful in the modelling of physical/biological/whatever systems, where each variable corresponds to particular physical concept or observable and there are few (or any) duplicate variables to make the definition of MTK "factories" worthwhile, while, there plenty of different physical representations, or _processes_ to represent the given physical concept.
+In many fields this approach parallels modelling reasoning line of the researcher more closely than the "components" approach.
 
-Beyond this reasoning style, the biggest strength of ProcessBasedModelling.jl is the informative errors it provides regarding incorrect/incomplete equations. When building the MTK model via ProcessBasedModelling.jl the user provides a vector of "processes": equations or custom types that have a well defined and single left-hand-side variable.
-This allows ProcessBasedModelling.jl to achieve the following:
+Beyond this reasoning style, the biggest strength of ProcessBasedModelling.jl is the **informative errors and automation** it provides regarding incorrect/incomplete equations. When building the MTK model via ProcessBasedModelling.jl the user provides a vector of "processes": equations or custom types that have a well defined and single left-hand-side variable.
+This allows ProcessBasedModelling.jl to:
 
-1. Iterates over the processes and collects _new_ variables that have been introduced by a provided process but do not themselves have a process assigned to them.
+1. Iterate over the processes and collect _new_ variables that have been introduced by a provided process but do not themselves have a process assigned to them.
 2. For these collected "process-less" variables:
-   - If there is a default process defined, it incorporates this one into the model
-   - If there is no default process but the variable has a default value, it equates the variable to a _parameter_ that has the same default value and throws an informative warning.
-   - Else, it throws an informative error saying exactly which originally provided variable introduced this new "process-less" variable.
-3. Also throws an informative error if a variable has two processes assigned to it (by mistake).
+   - If there is a default process defined, incorporate this one into the model
+   - If there is no default process but the variable has a default value, equate the variable to a _parameter_ that has the same default value and throw an informative warning.
+   - Else, throw an informative error saying exactly which originally provided variable introduced this new "process-less" variable.
+3. Throw an informative error if a variable has two processes assigned to it (by mistake).
 
-In our experience, and as we also highlight explicitly in the online documentation, this approach typically yields simpler, less ambiguous and more targeted warning/error messages than the native MTK one's, leading to faster identification and resolution of the problems with the composed equations.
+In our experience, and as we also highlight explicitly in the online documentation, this approach typically yields simpler, less ambiguous and more targeted warning or error messages than the native MTK one's, leading to faster identification and resolution of the problems with the composed equations.
 
 ProcessBasedModelling.jl is particularly suited for developing a model about a physical/biological/whatever system and being able to try various physical "rules" (couplings, feedbacks, mechanisms, ...) for a given physical observable efficiently.
 This means switching arbitrarily between different processes that correspond to the same variable.

docs/src/index.md

@@ -8,9 +8,11 @@ ProcessBasedModelling
 
 ## Usage
 
-In ProcessBasedModelling.jl, each variable is governed by a "process", which in code is just a symbolic expression from ModellingToolkit.jl.
-To coupled the variable with the process it is governed by, a user either defines simple equations of the form `variable ~ expression`, or creates an instance of [`Process`](@ref) if the left-hand-side of the equation needs to be anything more complex.
-Once all the processes about the physical system are collected, they are given as a `Vector` to the [`processes_to_mtkmodel`](@ref) central function. This function also defines what quantifies as a "process".
+In ProcessBasedModelling.jl, each variable is governed by a "process".
+Conceptually this is just an equation that _defines_ the given variable.
+To couple the variable with the process it is governed by, a user either defines simple equations of the form "variable = expression", or creates an instance of [`Process`](@ref) if the left-hand-side of the equation needs to be anything more complex. In either case, the variable and the expression are both _symbolic expressions_ created via ModellingToolkit.jl (more specifically, via Symbolics.jl).
+
+Once all the processes about the physical system are collected, they are given as a `Vector` to the [`processes_to_mtkmodel`](@ref) central function. This function also defines what quantifies as a "process" in more specificity.
 
 ## Example
 
@@ -109,6 +111,16 @@ equations(model)
 parameters(model)
 ```
 
+Lastly, [`processes_to_mtkmodel`](@ref) also allows the concept of "default" processes, that can be used for introduced "process-less" variables.
+For example,
+
+```@example MAIN
+model = processes_to_mtkmodel(processes[1:2], processes[3:3])
+equations(model)
+```
+
+does not throw any warnings as it obtained a process for ``y`` from the given default processes.
+
 ### Special handling of timescales
 
 In dynamical systems modelling the timescale associated with a process is a special parameter. That is why, if a timescale is given for either the [`TimeDerivative`](@ref) or [`ExpRelaxation`](@ref) processes, it is converted to a named `@parameter` by default: