Repository navigation
Development and Contribution Wiki Editing
The OSMOSE wiki is a shared space and everyone is welcome to help improve it. You do not need to be the expert on a topic to make a useful contribution. If you spot something unclear, incomplete, outdated or missing, please feel free to improve it. Small edits are just as valuable as large ones.
The wiki is meant to grow collaboratively over time and contributors should not hesitate to add, revise or reorganise content when it helps make the documentation better.
There are several good ways to contribute to the wiki:
- Expand an existing page. If a page is incomplete or unclear, you can open it and click Edit to add explanations, examples, clarifications, references or missing details.
- Fix or improve wording. If something is hard to follow, feel free to rephrase it to make it clearer and easier to read.
-
Leave a note for others. If you are not comfortable editing the text directly, you can leave an HTML comment in the source as a lightweight editorial note, for example:
<!-- This section may need an example --> - Create a new page. If a topic deserves its own page, you can create it from the wiki by clicking New Page, then adding a title and content.
-
Create links to missing topics. Even if you do not want to write the full page yet, adding a link to a page that should exist is already a useful contribution. In GitHub wikis, you can do this with
[[Page-name]]or with[[display text|Page-name]]if you want the link text to read differently. This is a simple way to highlight missing documentation and encourage someone to develop that page later. - Add helpful callouts. Notes, tips, warnings and similar callouts are also a useful way to improve pages by highlighting key information for readers.
Important
The wiki is now the main source of OSMOSE documentation, so keeping pages clear, accurate and connected is an important contribution to the model.
Note
The wiki does not need to be complete from the start. Pages can begin as short notes and improve progressively as more contributors add details, examples and clarifications.
Tip
You do not need to write a lot to help. Adding one clarification, one example or one missing link is already a valuable contribution.
Warning
Before making major changes to a page, make sure you are not accidentally removing information that may still be useful to others.
Caution
Avoid creating duplicate pages on the same topic, as this can make the documentation harder to navigate and maintain.
That is completely fine. A simple way to leave a remark, question or suggested correction is to add an HTML comment in the page source, for example:
<!-- This section may need an example for species parameterisation -->This is a practical way to leave editorial notes for other contributors without changing the visible content of the page.
Try to keep contributions practical and easy to follow. When possible:
- prefer clear headings and short sections;
- add examples when they help;
- include references when documenting technical concepts, assumptions or methods;
- link related pages together;
- update outdated content instead of duplicating it;
- keep the tone constructive and welcoming.
Perfection is not required. A page can start small and improve over time.
The OSMOSE wiki uses Markdown, so most edits only need a few simple conventions.
# Main title
## Section
### Subsection**bold**
*italic*
`code`- item
- item
1. first
2. second[Page title](full-url)GitHub wikis support the wiki-style syntax:
[[Installation]]
[[display text|Page-name]]
[[Life cycle|Life-cycle]]
[[How to contribute|Development-and-Contribution]]This is especially useful when you want to create a link to a page that does not exist yet, since it helps signal that the topic should eventually be documented.
You can also link to another wiki page with standard Markdown:
[Installation](Installation)
[Life cycle](Life-cycle)<!-- Add an example here -->GitHub wikis also support special callout boxes that are useful for notes, tips, important remarks, warnings and cautions:
> [!NOTE]
> Useful information that users should know, even when skimming content.
> [!TIP]
> Helpful advice for doing things better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.These are a nice way to improve a page without rewriting large sections of text.
```r
plot(x, y)
```| Column A | Column B |
|----------|----------|
| Text | Text |<details>
<summary>Click to expand</summary>
Extra details here.
</details>If you see something that can be improved, please improve it. If you are unsure, leave a note. If something is missing, create it. The wiki is a collaborative effort and contributions of all sizes are useful.