Liz: user documentation

[eromanova97]

Description

Fixes https://jira.suse.com/browse/TRNT-4270

• I have gathered the information from trento web and from different PRs linked in the epic.
• I targeted the documentation around the "about" section, since actually using the assistant is intuitive and does not need deep explanations (unless we want to provide some best practices, for now I just added some query examples I could think of).
• I have added a few comments to the draft for which I need additional info.
• If there is anything important missing that we want to explain to users, let me know and I will add it 👍

Preview

(old) Liz - SLES-SAP-trento_en.pdf
(new after restructuring) AI - SLES-SAP-trento_en.pdf

[eromanova97]

just a note: I forgot to update this in the trento web PR, so I am fixing that here

[abravosuse]

Good starting point, @eromanova97 . Thank you! I have made some comments and requested a few changes.

Also, in section Using Liz it would be nice to describe as well certain built functionality as: stop current query or copy results of last query.

Last but not least it might be worth it to mention as well certain important characteristics of Liz. For example, the fact that there is an internal configuration file that instructs Liz how to behave. Also, that all the output provided by Liz is in markdown format and when you copy are reply this enables you to paste it into a doc tool conserving the style.

[nelsonkopliku]

Hey @eromanova97 thanks for this!

An thanks for the feedback

actually using the assistant is intuitive and does not need deep explanations

I added a couple of comments just to provide more context, they are by no means a change request or a suggestion to add images (the visuals are there just to clarify the comment).

Feel free to disregard if you were already aware of those.

---

Now the real feedback.

Overall information architecture about AI

We currently have two entries in the navigation:

• MCP Integration
• Liz AI assistant in Trento Web

I would say that they both fall within a broader "AI in trento" kind of thing (naming/wording up to you).
What do you think about restructuring in that direction where we have a general AI in trento entry and then we unpack the specifics? Liz/MCP/others in the future

Or at least inverting the order.

Liz/MCP contrapposition

When I look at the following excerpt

Unlike the {tr_mcp}, which is an optional component you install separately to connect external AI tools to {trento}, {liz} is part of {tr_web} itself. You only need to supply an API key for a supported large language model (LLM) provider.

I understand it comes from the fact we had the mcp server first and we are adding now Liz, hence we are making this differentiation.

However in the context of a revised information architecture about AI and in relation to how the thing works (Liz is built-in while mcp is an optional component) I would find a narrative starting from Liz and then going to mcp server to reflect closer the reality.

Like: hey, in trento you have Liz and then if you want to connect external ai clients/tools you can do so by installing this extra component.

I understand it would require revisiting also pre-existing doc about mcp server, though.

Let me know what you think. Happy to answer any question.

[antgamdia]

Thanks! Just in case, please have a look at what out colleagues in Rancher did: https://documentation.suse.com/cloudnative/rancher-ai/1.1.0/en/introduction.html

Edit: perhaps https://documentation.suse.com/cloudnative/rancher-ai/1.1.0/en/how-tos/how-to-admin.html#upgrading-liz also

Not now, but perhaps we could adopt some of the "how-to" sections they have in the future.

[nelsonkopliku]

Great work @eromanova97! Thanks a lot! 🚀

Let's gather another round of review after this restructuring.

[nelsonkopliku]

@abravosuse in Liz we have the disclaimer "AI assistants can make mistakes." an then the link to Learn more that opens trento documentation.

Are we good with that link or should we change it to something different?

[eromanova97]

NOTE REGARDING RESTRUCTURING CHANGES:

• Because the restructuring required putting the MCP chapter one level deeper, I had to slightly flatten the MCP section structure. No text changes were made other than in the introduction (to mention Liz there). I also fixed some small errors that I noticed, but nothing major.