[Docs] Revise Vizro-AI docs to align with style guide

vizro-ai/changelog.d/20240325_170323_jo_stichbury_revise_vizro_ai_docs.md

@@ -0,0 +1,48 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Highlights ✨
+
+- A bullet item for the Highlights ✨ category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Removed
+
+- A bullet item for the Removed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Added
+
+- A bullet item for the Added category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Changed
+
+- A bullet item for the Changed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->

vizro-ai/docs/index.md

@@ -1,47 +1,32 @@
 # Vizro-AI
 
-Vizro-AI is a tool designed for generating data visualizations. It serves as an extension to Vizro, leveraging natural language capabilities to empower users in creating charts effortlessly.
+Vizro-AI extends [Vizro](https://vizro.readthedocs.io) with a user-friendly interface that uses natural language capabilities to help you create interactive charts effortlessly.
 
-## Why Vizro-AI?
-
-### Easy-to-use
-One of the key strengths of Vizro-AI lies in its natural language capabilities, making it accessible to coding novices. Vizro-AI provides a user-friendly interface that allows to create interactive charts while offering detailed insights about the data and the generated code.
-
-### Visually-optimized
-Vizro-AI also caters to data practitioners who often find themselves spending more time in formatting rather than actual visualization creation. Vizro-AI enables users to speed up the process of creating visually appealing charts by using Vizro's themes which incorporate design best practices by default.
-
-### Dashboard-ready
-Vizro-AI leverages the power of [Plotly](https://plotly.com/python/) to produce interactive charts, making it easier to seamlessly integrate these generated charts directly into dashboard applications.
-
-!!! notice "Notice"
-    Please review this [disclaimer](pages/explanation/disclaimer.md)
-    before using the `vizro-ai` package.
-
-    Since users must connect to Large Language Models (LLMs) in order to use Vizro-AI,
-    please also ensure that you review our guides on the [usage of LLMs](pages/explanation/safety-in-vizro-ai.md)
-    and the required [safeguarding for dynamic code evaluation](pages/explanation/safeguard.md).
+If you're new to coding, Vizro-AI simplifies the process of creating charts that offer detailed insights about your data. Even if you're an experienced data practitioner, Vizro-AI optimizes how you create visually appealing charts.
 
+* It uses Vizro's themes, which incorporate design best practices by default.
+* It uses [Plotly](https://plotly.com/python/) and makes it easy to integrate the interactive charts it generates seamlessly into dashboard applications.
 
 <div class="card-section-wrapper" style="display: block;">
 <div class="responsive-grid">
 
 <a class="card-wrapper" href="pages/tutorials/quickstart/">
   <div class="card">
     <div class="card-content">
-      <h5>Get Started</h5>
+      <h5>Get started</h5>
       <p>
-        New to Vizro-AI? Take a look at our tutorials to get started and to explore our core features.
+        New to Vizro-AI? Tutorials to get started and to explore the key features.
       </p>
     </div>
   </div>
 </a>
 
-<a class="card-wrapper" href="pages/user-guides/install/">
+<a class="card-wrapper" href="pages/user-guides/run-vizro-ai/">
   <div class="card">
     <div class="card-content">
-      <h5>User Guides</h5>
+      <h5>How-to guides</h5>
       <p>
-        Our user guides provide step-by-step instructions on how to install `vizro-ai` package and leverage our core features.
+        Step-by-step instructions on how to use Vizro-AI.
       </p>
     </div>
   </div>
@@ -53,7 +38,7 @@ Vizro-AI leverages the power of [Plotly](https://plotly.com/python/) to produce
     <div class="card-content">
       <h5>Explanation</h5>
       <p>
-        Our explanation section contains background information and disclaimer.
+        The explanation section contains background information and a disclaimer.
       </p>
     </div>
   </div>
@@ -64,11 +49,19 @@ Vizro-AI leverages the power of [Plotly](https://plotly.com/python/) to produce
     <div class="card-content">
       <h5>Contribute</h5>
       <p>
-        Find our contribution guidelines and all our current and previous contributors here.
+        Contribution guidelines and all our current and past contributors.
       </p>
     </div>
   </div>
 </a>
 
 </div>
 </div>
+
+!!! notice "Notice"
+    Please review this [disclaimer](pages/explanation/disclaimer.md)
+    before using the `vizro-ai` package.
+
+    Users must connect to Large Language Models (LLMs) to use Vizro-AI.
+    Please review our [guidelines on the use of LLMs](pages/explanation/safety-in-vizro-ai.md)
+    and the required [safeguarding for dynamic code evaluation](pages/explanation/safeguard.md).

vizro-ai/docs/pages/contribute/authors.md

@@ -1,17 +1,17 @@
 # Authors
 
 ## Current team members
-
+[Alexey Snigir](https://github.com/l0uden),
 [Anna Xiong](https://github.com/Anna-Xiong),
-[Maximilian Schulz](https://github.com/maxschulz-COL),
-[Chiara Pullem](https://github.com/chiara-sophie),
-[Lingyi Zhang](https://github.com/lingyielia),
 [Antony Milne](https://github.com/antonymilne),
-[Alexey Snigir](https://github.com/l0uden),
+[Chiara Pullem](https://github.com/chiara-sophie),
+[Dan Dumitriu](https://github.com/dandumitriu1),
 [Huong Li Nguyen](https://github.com/huong-li-nguyen),
-[Petar Pejovic](https://github.com/petar-qb),
+[Jo Stichbury](https://github.com/stichbury),
+[Joseph Perkins](https://github.com/Joseph-Perkins),
+[Lingyi Zhang](https://github.com/lingyielia),
+[Maximilian Schulz](https://github.com/maxschulz-COL),
 [Nadija Graca](https://github.com/nadijagraca),
-[Joseph Perkins](https://github.com/Joseph-Perkins)
+[Petar Pejovic](https://github.com/petar-qb).
 
-with thanks to Sam Bourton and Stephen Xu for sponsorhip, inspiration and guidance,
-(plus everyone else who helped to test, guide, support and encourage development)
+With thanks to Sam Bourton and Stephen Xu for sponsorship, inspiration and guidance, plus everyone else who helped to test, guide, support and encourage development.

vizro-ai/docs/pages/contribute/contributing.md

@@ -1 +1 @@
-# Contributing Guidelines
+# Contributing guidelines

vizro-ai/docs/pages/explanation/disclaimer.md

@@ -1,17 +1,19 @@
 # Disclaimer
 
-Users must select one of the [supported Large Language Models (LLMs)](../user-guides/model-config.md) in order to use the `vizro_ai` package,
+Users must select one of the [supported large language models (LLMs)](../user-guides/faq.md#which-llms-are-supported-by-vizro-ai) to use the `vizro_ai` package,
 and are responsible for obtaining their own suitable API key for the relevant model.
 
-## Third Party API
+<!-- vale off -->
+
+## Third party API
 
 - Users are responsible for anything done via their own API key.
 
 - Users are responsible for procuring any and all rights necessary to access any third-party generative AI tools and for complying with any applicable terms or conditions thereof.
 
 - Users are wholly responsible for the use and security of the third-party generative AI tools and of Vizro.
 
-## User Acknowledgments
+## User acknowledgments
 
 Users acknowledge and agree that:
 
@@ -33,3 +35,4 @@ The Outputs shall be verified and validated by the users and shall not be used w
 Users remain solely responsible for the use of the Output, in particular, the users will need to determine the level of human oversight needed to be given the context and use case,
 as well as for informing the users’ personnel and other affected users about the nature of the GenAI Output.
 Users are also fully responsible for their decisions, actions, use of Vizro and Vizro-AI and compliance with applicable laws, rules, and regulations, including but not limited to confirming that the Outputs do not infringe any third-party rights.
+<!-- vale on -->

vizro-ai/docs/pages/explanation/safeguard.md

@@ -1,23 +1,23 @@
-# Safeguard Dynamic Code Execution in Vizro-AI
+# Safeguard dynamic code execution in Vizro-AI
 
-Vizro-AI uses the `exec()` statement in Python to run generated code from Large Language Models (LLMs) for
+Vizro-AI uses the `exec()` statement in Python to run generated code from large language models (LLMs) for
 self-debugging and automatic visual rendering in methods such as `vizro_ai._get_chart_code()` and `vizro_ai.plot()`.
-One of the primary concerns is the potential for malicious code to access or modify critical system resources or data.
+One of the primary concerns is the potential for malicious code to access or change critical system resources or data.
 
 ## Understand `exec()`
 
-The `exec()` function allows for the dynamic execution of Python programs which can either be a string or object code.
+The `exec()` function enables the dynamic execution of Python programs which can either be a string or object code.
 While it offers great flexibility, it also poses a significant security risk, especially when executing untrusted code.
 
 ## Safeguarding code execution
 
 While we have made considerable efforts to safeguard its usage by limiting the usage to specific modules and functions and by restricting certain built-in operations,
-these measures cannot guarantee absolute security. It is imperative for users to take additional precautions.
+these measures cannot guarantee absolute security. It is imperative for users to take extra precautions.
 
 ### Our effort on safeguarding code execution in Vizro-AI
 
 To help to mitigate these risks, we limit the execution of certain modules and functions.
-One approach is to leverage Python's built-in sys module to restrict access to unsafe modules or functions.
+One approach is to use Python's built-in `sys` module to restrict access to unsafe modules or functions.
 By defining a whitelist of safe modules and packages and restricting certain built-in functions.
 
 !!! Warning
@@ -77,10 +77,10 @@ The lists below are a reflection of the security and functionality we have imple
 
 ### Safeguard for user environment and input
 
-- **Isolated Environment**: Always run code in an isolated or contained environment, such as a virtual environment,
+- **Isolated environment**: Always run code in an isolated or contained environment, such as a virtual environment,
   virtual machine or container, to minimize potential harm to the primary system.
 
-- **Avoid Malicious Input**: Never feed untrusted or malicious input. Regardless of safeguards,
+- **Avoid malicious input**: Never feed untrusted or malicious input. Regardless of safeguards,
   there's always a risk associated with executing dynamic code.
   It remains the user's responsibility to ensure the safety and appropriateness of executing any generated code,
   particularly in sensitive or critical contexts.

vizro-ai/docs/pages/explanation/safety-in-vizro-ai.md

@@ -1,57 +1,56 @@
-## Warning and Safety usage for Generative AI Models
+## Warning and safety usage for generative AI models
 
-Generative AI models, especially Large Language Models (LLMs) represent significant advancements in the AI field.
-Vizro-AI also leverages LLMs, however, as with any powerful tool, there are potential risks associated.
+Vizro-AI uses generative AI models because large language models (LLMs) represent significant advancements in the AI field. However, as with any powerful tool, there are potential risks associated with connecting to a generative AI model.
 
-Users must connect to a generative AI model, specifically LLMs to use Vizro-AI.
 We recommend users research and understand the selected model before using `vizro_ai` package.
 
 Users are encouraged to treat AI-generated content as supplementary, **always apply human judgment**,
 approach with caution, review the relevant [disclaimer](disclaimer.md) page, and consider the following:
 
-### 1. Hallucination and Misrepresentation
-
+### 1. Hallucination and misrepresentation
+<!-- vale off -->
 Generative models can potentially generate information while appearing factual, being entirely fictitious or misleading.
+<!-- vale on -->
 The vendor models might lack real-time knowledge or events beyond its last updates.
-`vizro_ai` output may vary and please always verify critical information.
+`vizro_ai` output may vary and you should always verify critical information.
 It is the user's responsibility to discern the accuracy, consistent, and reliability of the generated content.
 
-### 2. Unintended and Sensitive output
+### 2. Unintended and sensitive output
 
 The outputs from these models can be unexpected, inappropriate, or even harmful.
 Users as human in the loop is an essential part. Users must check and interpret the final output.
 It is necessary to approach the generated content with caution, especially when shared or applied in various contexts.
 
-### 3. Data Privacy
+### 3. Data privacy
 
 Your data is sent to model vendors if you connect to LLMs via their APIs.
 For example, if you connect to the model "gpt-3.5-turbo-0613" from Open AI, your data will be sent to OpenAI via their API.
 Users should be cautious about sharing or inputting any personal or sensitive information.
 
-### 4. Bias and Fairness
+### 4. Bias and fairness
 
 Generative AI can exhibit biases present in their training data.
 Users need to be aware of and navigate potential biases in generated outputs and be cautious when interpreting the generated content.
 
-### 5. Malicious Use
+### 5. Malicious use
 
 These models can be exploited for various malicious activities. Users should be cautious about how and where they deploy and access such models.
 
 It's crucial for users to remain informed, cautious, and ethical in their applications.
 
-## Dependencies, Code Scanners and Infosec
+## Dependencies, code scanners and information security
 
-It may occur that dependencies of `vizro_ai` get flagged by code scanners and other infosec tools. As a consequence it may happen that
+It may occur that dependencies of `vizro_ai` get flagged by code scanners and other information security tools. As a consequence it may happen that
 `vizro_ai` also get flagged.
 
-While we aim to resolve any flagged issues as soon as possible, there may not always be an immediate available fix, especially in a very dynamic environment such as generative AI. We encourage users to investigate if any flagged infosec issues are actually related
+While we aim to resolve any flagged issues as soon as possible, there may not always be an immediate available fix, especially in a dynamic environment such as generative AI. We encourage users to investigate if any flagged information security issues are actually related
 to any functionality used in our code base or if they only concern functionality outside the scope of `vizro_ai`.
 
 In case those issues are related to code execution, note that `vizro_ai` has its own process of executing dynamic code (see [Safeguard Execution of Dynamic Code](safeguard.md)), and does not rely on its dependencies to do so.
 
-## Execution of Dynamic Code in Vizro-AI
+## Execution of dynamic code in Vizro-AI
 
-The `exec()` statement is used in `vizro_ai`. It allows for dynamic execution of Python programs which can be powerful, but can also pose security risk
+The `exec()` statement is used in `vizro_ai`. It enables dynamic execution of Python programs which can be powerful, but can also pose security risk
 if used without caution. When paired with outputs from generative models, there is potential for unintended or malicious code execution.
 
 Users must exercise caution when executing code generated by or influenced by AI models. It's essential to:
@@ -62,4 +61,4 @@ Users must exercise caution when executing code generated by or influenced by AI
 - Always be aware that malicious code execution cannot be mitigated with 100% certainty
 - Always review and understand the selected model before connecting with `vizro_ai`
 
-If you would like to learn more about our efforts in safeguarding code execution, please refer to [Safeguard Execution of Dynamic Code](safeguard.md) for more information.
+If you would like to learn more about our efforts in safeguarding code execution, refer to [Safeguard Execution of Dynamic Code](safeguard.md) for more information.