# Writing diagram prompts

The difference between a useful draft and a useless one is almost always the prompt, not the model.

---

## The pattern that works

| **Include**                  | **Example**                                                       |
| ---------------------------- | ----------------------------------------------------------------- |
| **The notation**             | "A Mermaid sequence diagram"                                      |
| **The actors or components** | "between the mobile app, the API gateway and the auth service"    |
| **The flow, in order**       | "login request, token issued, token validated on each later call" |
| **What to leave out**        | "do not show error handling"                                      |

## Compare

| **Weak prompt**        | **Strong prompt**                                                                                                                                                                                                                       |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A diagram of our login | A Mermaid sequence diagram of login: the mobile app posts credentials to the API gateway, which calls the auth service; the auth service returns a JWT; later calls carry the JWT and the gateway validates it locally. No error paths. |
| Show the architecture  | A draw.io style component diagram of three services (web, api, worker) with a shared Postgres and a Redis queue, showing which service talks to which store.                                                                            |

📝

**Name your own components.** The model does not know your service names unless you supply them, and it will happily invent some.

---

## A few things that catch people out

* Longer prompts genuinely work better here. This is not a search query.
* Asking for a notation you have not enabled produces a fallback, not an error.
* If two attempts both miss, describe the diagram structurally rather than narratively.

---

## Related

[Create diagrams with AIUsing the prompt.](https://help.gocapable.com/diagrams/ai-diagramming.html)

[Diagram StudioRefining rather than re-prompting.](https://help.gocapable.com/diagrams/ai-diagramming.html)

[Diagram typesKnowing which notation to name.](https://help.gocapable.com/diagrams/diagram-types.html)

---

_Name the notation, the parts, and the order._