How to write better queries for smart template diagrams
Query writing, also known as prompt engineering, is becoming an important skill as large language models and AI tools become more popular. It is hard to write a good query to ensure a good outcome from any type of content generator. Here’s how you can make the most of the smart templates feature in draw.io.
How it works
Enter a text query in the template manager and draw.io submits it to a large language model tool (in this case, ChatGPT) which processes your query and returns a diagram in Mermaid syntax. draw.io then converts this to use the built-in draw.io shapes so you can style and update your diagram easily after you add the generated template to the canvas.
Smart template diagrams are a good start for simpler types of diagrams, such as flowcharts, sequence diagrams, concept maps and tree diagrams. Mermaid does not support technical diagrams with more complex notations such as AWS, Azure, BPMN, and so on. But you can easily drag and drop these from their shape libraries in draw.io to replace the generic shapes used in your generated template.
Important: As with all AI or smart content generation tools, you should not include any sensitive information - don’t include any private, personal and confidential business information in any query you write.
Smart templates are disabled by default if you are using the draw.io apps for Confluence or Jira Cloud. Ask your administrator to enable this option in the draw.io configuration.
Generate a smart template diagram
Open the template library: Click Arrange > Insert > Template or create a new diagram to open the template library dialog. If you use Simple mode or the Sketch editor theme, click on + in the toolbar and select Template.
-
Generate a diagram from text: Click on the Generate box on the first page of the template library to show a text box where you can enter your text query. Press
Enteror click OK to submit it to the generator.
-
Choose a diagram type and generate it from text: Go to the Smart Templates section where you can select a diagram type from a list. Enter your query and click Generate.
Generate another version using the same description
The smart template will be different each time you generate or regenerate it using the same query.
Edit your query - click the pencil in the top right - and resubmit it to generate a different version of your diagram. Click on the magnifying glass in the top right to see a larger preview of your diagram.
If you are in the Smart Template section, click Generate again to regenerate the preview.
Read on for the tips to write better queries and generate better smart template diagrams.
Write the diagram type first
This will tell the generator to limit the diagram type to the one you want. For example, a sequence diagram.
sequence diagram - a customer purchases a product from an online store
Tip: Add vertical or horizontal to tell the generator to draw the diagram in that direction.
Keep the language simple and consistent
Keep your language simple and direct, use punctuation and multiple sentences. Make sure you use the same term to consistently refer to each actor or system in your diagram.
The following examples are increasingly more complex than the prompt used for the sequence diagram above.
flowchart - A customer signs up for a 14-day trial software license.
After 10 days, a sales engineer contacts the customer to learn their
requirements, then writes the customer a quote.
If the customer does not accept the quote,
their software license is invalidated on day 15.
If the customer accepts the quote, they can continue to use the software.
Add detail for a more accuracy
If you want to have a detailed and appropriate smart template and not have to do too much editing to get to the final diagram, you will need to include all the important details.
Using the example above, the customer who chooses not to accept the quote must not be allowed to start another free trial.
vertical flowchart -
A customer signs up for a 14-day trial software license.
Has the customer already had a trial license?
Yes - the customer must contact a sales engineer.
No - Customer can use the software for 14 days.
After 10 days, a sales engineer contacts the customer
to learn the customer's requirements and writes the customer a quote.
As you can see, smart templates - and any generated content - almost always need editing. The customer should receive a quote, not a tailored solution.
Break it up into multiple short queries
As the generator only accepts short queries, and ignores anything past a certain length, you’ll need to break your description into parts and add multiple smart templates to the drawing canvas.
For example, let’s remove the tailored solution step from the previous example, and insert a second smart template for the remaining steps in the process.
vertical flowchart -
The sales engineer writes a quote to the customer.
If the customer does not accept the quote,
their software license is invalidated on day 15
and their email address is added to a block list.
If the customer accepts the quote, and payment is
processed successfully, they can continue to use the software.
Open this example in the draw.io viewer
Use terms from the Mermaid syntax
As the generator outputs a diagram using Mermaid syntax, you can get better results when using the terms from the Mermaid syntax documentation to describe its diagrams. For example, user journeys are broken into sections which contain tasks that have a happiness value.
journey diagram - title Work day - two sections
Productive section has - task brainstorming value 5,
task meeting value 2, task pair programming value 3.
Leisure section has - task lunch value 5, task yoga value 5.
Compare this to a more natural description of the rating system - using high, average and low instead of numerical values.
journey - Show how I break my work day into two.
When I'm productive, I rate brainstorming high, meeting low
and pair programming average, and in my leisure time, I have
lunch and do yoga, and rate both highly
