---
title: "Quickstart"
description: "Create, share, and improve your first Merfolk diagram."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.merfolk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

Merfolk keeps the diagram and the conversation around it together. This guide takes you through the complete product workflow in the web app: make a visual reference, share it with the people who know the work, and turn their feedback into the next version.

## 1. Start with a question

Choose something your team needs to make visible:

- A process that is difficult to explain
- A system or architecture that has changed
- A customer journey or operational workflow
- A decision that needs shared context

Open the [Merfolk web app](https://app.merfolk.io) and create a diagram. Give it a title that makes its purpose clear to someone who did not create it.

## 2. Create the first version

Describe the main steps, services, people, or decisions. You can start with a small diagram and add detail as the team learns more.

For example, a simple system map might begin with:

```mermaid
graph TD
  Browser --> API
  API --> Database
```

The editor shows the Mermaid source alongside the rendered diagram. Use the preview to check whether the structure is understandable, then let the editor save your changes.

Read [Create and edit diagrams](/web/diagrams/create-and-edit) for the editor workflow and source-format guidance.

## 3. Share the visual reference

Open **Share** to copy the diagram link. Choose the visibility that fits the work before sending it:

- Use **public** visibility for diagrams that are safe to share broadly.
- Use **private** visibility for internal architecture, unfinished work, or team material.

See [Share diagrams](/web/diagrams/share) for sharing guidance and [Diagram visibility](/web/visibility) for the access model.

## 4. Collect feedback on the diagram

Ask reviewers to comment on the part they understand best. Comments can capture questions, missing paths, and follow-up tasks without requiring reviewers to edit the source.

For example:

- “What happens when the API is unavailable?”
- “This step is owned by operations, not engineering.”
- “Add the approval path before the release.”

Read [Comments and collaboration](/web/diagrams/comments) to learn how review works.

## 5. Update the shared picture

An approved editor turns the useful feedback into a new source version. Keep the diagram focused on the question it should answer, then share the updated result again.

This is the Merfolk loop:

1. Create a useful first version.
2. Share it with the people who know the work.
3. Collect feedback where it belongs: on the diagram.
4. Update the source and continue the conversation.

## Choose another workflow

The web app is the easiest place to start, but the same diagram workflow can begin wherever your work already happens:

- [CLI quickstart](/cli/quickstart) — create and update diagrams from a terminal, script, or automation.
- [Merfolk for agents](/agents/overview) — have a coding agent create or update diagrams from working context.
- [Web app overview](/web/overview) — learn how the workspace, editor, teams, and sharing fit together.

Source: https://docs.merfolk.io/getting-started/quickstart/index.mdx