Skip to content

Commit 928e07a

Browse files
reint-fischerreint-fischer
authored andcommitted
add hard wrapping recommendation to docsguide
1 parent c430817 commit 928e07a

File tree

1 file changed

+18
-5
lines changed

1 file changed

+18
-5
lines changed

docs/development/docsguide.md

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@
22

33
## Vision
44

5-
We believe a clear documentation is important to community building, reproducibility, and transparency in our open-source project. To make it easier to write our documentation in a consistent way, here we outline a brief vision for our documentation based heavily on a few common resources.
5+
We believe a clear documentation is important to community building, reproducibility, and transparency in our open-source
6+
project. To make it easier to write our documentation in a consistent way, here we outline a brief vision for our
7+
documentation based heavily on a few common resources.
68

79
```{note}
810
TODO: outline functions of the documentation based on resources
@@ -17,15 +19,26 @@ TODO: outline functions of the documentation based on resources
1719

1820
## Notebook execution
1921

20-
We run the notebooks in our documentation using [MyST-NB](https://myst-nb.readthedocs.io/en/latest/index.html). Here is a table showing the latest notebook execution:
22+
We run the notebooks in our documentation using [MyST-NB](https://myst-nb.readthedocs.io/en/latest/index.html). Here is
23+
a table showing the latest notebook execution:
2124

2225
```{nb-exec-table}
2326
2427
```
2528

2629
## Style guide
2730

28-
- **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`.
29-
- [**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.
31+
- **Write out `parcels.class.method` in tutorials and how-to guides** so that we can see which classes and methods are
32+
part of Parcels. Because in the alternative (using `from parcels import class`) the use of `class` in a cell further
33+
along is not obviously part of `parcels`.
34+
- [**Avoid too much Repitition In Documentation**](https://www.writethedocs.org/guide/writing/docs-principles/#arid):
35+
tutorials and how-to guides notebooks will often have repetition of the general **Parcels** steps, which is fine because
36+
we want readers to see the changes to a specific class or method in the context of the simulation, e.g. `Particle` and
37+
`Kernel` are often customised together, which must be defined before the `ParticleSet.execute()`. We try to limit each
38+
page in the documentation to a small number of examples.
3039
- **Import packages at the top of the section in which they are first used** to show what they are used for.
31-
- **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".
40+
- **Write documentation in first person plural ("we").** In our open source code, tutorials and guides can be written
41+
by any developer or user, so the documentation teaches all of us how to do something with Parcels. Sometimes it can be
42+
more natural to take on the tone of a teacher, writing to a student/learner, in which case it is okay to use "you".
43+
Please refrain from using impersonal subjects such as "the user".
44+
- We recommend hard wrapping prose in markdown so that reading it becomes easier in any editor.

0 commit comments

Comments
 (0)