Apply writing suggestions from code review

Co-authored-by: Nick Hodgskin <[email protected]>

Author: reint-fischer

docs/development/docsguide.md

@@ -25,7 +25,8 @@ We run the notebooks in our documentation using [MyST-NB](https://myst-nb.readth
 
 ## Style guide
 
-- **Write out `parcels.class.method` in tutorials and how-to guides** so that we can see which classes and methods are part of Parcels. Because in the alternative (using `from parcels import class`) the use of `class` in a cell further along is not obviously part of `parcels`.
-- [**Avoid too much Repitition In Documentation**](https://www.writethedocs.org/guide/writing/docs-principles/#arid): tutorials and how-to guides notebooks will often have repetition of the general **Parcels** steps, which is fine because we want readers to see the changes to a specific class or method in the context of the simulation, e.g. `Particle` and `Kernel` are often customised together, which must be defined before the `ParticleSet.execute()`. We try to limit each page in the documentation to a small number of examples.
+- **Prefer `import parcels` over `from parcels import class` in tutorials and how-to guides** so its obvious in later code cells which classes and methods are part of Parcels.
+- [**Avoid too much Repitition In Documentation**](https://www.writethedocs.org/guide/writing/docs-principles/#arid): tutorials and how-to guides notebooks will often have repetition of the general **Parcels** steps, (e.g., imports ) - this is needed so that users have complete examples that they can copy and experiment with.`. We try to limit each page in the documentation to a small number of examples.
+- Introduce links and cross-references to maximize discoverability of documentation. This also reduces the necessity for repetition in notebooks.
 - **Import packages at the top of the section in which they are first used** to show what they are used for.
 - **Write documentation in first person plural ("we").** In our open source code, tutorials and guides can be written by any developer or user, so the documentation teaches all of us how to do something with Parcels. Sometimes it can be more natural to take on the tone of a teacher, writing to a student/learner, in which case it is okay to use "you". Please refrain from using impersonal subjects such as "the user".