> For the complete documentation index, see [llms.txt](https://help.modelreef.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.modelreef.io/help/permissions-and-collaboration/notes-and-comments.md).

# 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)