# Notes & Comments

This article explains how **notes and comments** work in Model Reef.

You will learn:

* How to use notes to document assumptions.
* How to use comments to support review and discussion.
* How roles and permissions affect notes and comments.

Notes and comments are key tools for keeping complex models understandable and auditable.

{% stepper %}
{% step %}

### Notes

**Notes** are used to attach context to a model object.

You can add notes to:

* Variables and drivers.
* Branches.
* Data Library entries.
* In some cases, dashboards or report elements.

Typical note content includes:

* Explanation of an assumption or formula.
* Source of numbers, for example a contract or report.
* Summary of a decision or rationale.
* Links to external documents or references.

Notes are long lived and intended to be read by anyone who works on the model later.
{% endstep %}

{% step %}

### Comments

**Comments** are used for discussion and review.

You can use comments to:

* Ask questions about an assumption.
* Request changes from another team member.
* Record feedback from stakeholders.
* Mark items as approved or needing follow up.

Comments are usually structured as short, threaded messages attached to a specific object.
{% endstep %}

{% step %}

### Roles and access

Permissions behave as follows:

* **Owners and Editors**
  * Can add, edit and delete notes and comments on objects they can access.
* **Viewers**
  * Can read notes and comments on objects they can access.
  * Cannot create or modify notes or comments.

Branch level permissions determine which objects a user can see. If a user cannot see a branch, they also cannot see notes or comments attached to it.
{% endstep %}

{% step %}

### Best practices for notes and comments

To keep collaboration effective:

* Use notes for stable documentation and comments for conversation.
* Include dates, names and key decisions in notes where appropriate.
* Resolve comment threads once actions are complete.
* Avoid placing critical assumptions only in external emails or chats. Keep a copy in the model.

This makes it much easier to revisit and audit the model in the future.
{% endstep %}
{% endstepper %}

## Related articles

* [Asset Replacement Planning](/use-cases/logistics-transport-and-fleet/asset-replacement-planning.md)
* [Dashboards & Reporting](/how-tos/dashboards-and-reporting.md)
* [Parent/Child Behaviour](/help/building-your-model/parent-child-behaviour.md)
* [How Input Fields Work](/syntax/how-input-fields-work.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.modelreef.io/help/permissions-and-collaboration/notes-and-comments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.