Maia Best Practices

content/en/docs/mendix-portal/maia-portal.md

@@ -51,7 +51,7 @@ You can access Maia Chat in Mendix Portal by clicking the **Maia** ({{% icon nam
 
 The chat interface appears at the right side of your browser window. You can start using Maia Chat either by clicking one of the demo questions or by asking your own question in the chatbox. 
 
-### Asking Follow-Up Questions
+### Asking Follow-Up Questions {#follow-up}
 
 Maia Chat supports asking follow-up questions based on your previous question and the answer you have received. For example, you can ask it to summarize the latest answer you received by typing *Can you summarize that?*.
 
@@ -60,3 +60,41 @@ Maia Chat supports asking follow-up questions based on your previous question an
 Maia Chat only keeps track of a conversation history within a session on a page in Mendix Portal.
 
 {{% /alert %}}
+
+## Best Practices {#best-practices}
+
+Maia can normally provide a good answer to any question you pose. However, it may sometimes not give you the information you are looking for. You may get a better answer if you consider the following best practices.
+
+### Asking Questions in English
+
+Maia is trained on data which is primarily in English. Although Maia can cope with questions in other languages, the imprecision of (particularly machine-) translation means there is more chance of Maia misunderstanding or giving a less precise answer.
+
+### Asking Direct Questions
+
+Maia is trained on the Mendix documentation and the Mendix Community. The documentation is addressed to you, the reader, and questions to the Community are usually asked directly by the person who is asking. Maia therefore gives better answers if you put yourself in the position of asking the question.
+
+So, for example, ask "How can I do something" rather than "How can my colleague do something" or "How does Mendix do something".
+
+### Giving Relevant Information
+
+Maia needs to know as much as possible about what you are doing. However, it can be sidetracked if you include information which is not directly relevant to what you are asking. So ensure that you do not include irrelevant information.
+
+However, do include enough information for context. For example, if you ask "How do I sign in to Mendix" it will not necessarily be clear whether you are talking about the Mendix Portal, Studio Pro, or perhaps even your deployed Mendix App, so give Maia the complete context to ensure the answer is relevant. 
+
+### Using Mendix Terminology
+
+Maia will provide better answers if you use Mendix terminology which it can recognize from the documentation and Community. If you use different terms, Maia may struggle to find the right answer, and is more likely to get confused about the subject of your question.
+
+For example, use "Studio Pro" rather than "the IDE" when talking about working on a Mendix model. If you have a question about a Marketplace module, make sure you give the exact name of the module.
+
+### Using Follow Up Questions
+
+If Maia does not give a response which clearly answers your question, try following up to ensure that it has understood the context and terminology you are using.
+
+### Separating Different Questions
+
+If you are asking a second, unrelated, question, start a new interaction with Maia. If you continue in the same chat with Maia, it will remember what you asked before and the answers it gave. This may lead to it using the information from the previous interactions as input to your new question. See [Asking Follow-Up Questions](#follow-up) to see when Maia keeps track of conversation history.
+
+### Looking at the Source Material
+
+Maia will give references to the source of the information. The reference titles can indicate whether the information is relevant to your case, and following the links may give additional help.

content/en/docs/refguide/modeling/mendix-ai-assistance/maia-chat.md

@@ -49,6 +49,8 @@ You can start using Maia Chat by clicking one of the demo questions. Alternative
 
 For more information on Maia Chat features in Studio Pro, see the sub-sections below.
 
+If Maia is not giving you a good answer, check the [best practices](/portal/maia/#best-practices) in *Maia in Mendix Portal*. If you still can't get a good answer, please see [Giving Feedback](#feedback), below for information on how to let Mendix know.
+
 ### Maia Chat Features in Studio Pro
 
 After a question is sent to Maia Chat, you will see the following in the chat interface:
@@ -61,7 +63,7 @@ After a question is sent to Maia Chat, you will see the following in the chat in
 * A copy icon ({{% icon name="copy" %}}) which allows you to copy the given answer to a clipboard
 * Feedback icons
 
-#### Giving Feedback
+#### Giving Feedback {#feedback}
 
 Mendix encourages giving feedback on the answers generated by Maia Chat. Feedback will be used to further improve Maia Chat.