[Docs] Edit docs for readability part 1

.gitignore

@@ -85,7 +85,8 @@ instance/
 # Scrapy
 .scrapy
 
-# mkdocs
+# mkdocs and docs
+vizro-core/docs/.vale
 vizro-core/site
 vizro-ai/site
 

vizro-core/changelog.d/20240227_123915_jo_stichbury_light_edit_for_readability.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-core/docs/index.md

@@ -11,7 +11,7 @@ Vizro is a toolkit for creating modular data visualization applications.
     <div class="card-content">
       <h5>Get Started</h5>
       <p>
-        New to Vizro? Take a look at our tutorials to get started and to explore our core features.
+        New to Vizro? Tutorials to get started and to explore the key features.
       </p>
     </div>
   </div>
@@ -20,9 +20,9 @@ Vizro is a toolkit for creating modular data visualization applications.
 <a class="card-wrapper" href="pages/user_guides/install/">
   <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 leverage our core features.
+        Step-by-step instructions on how to use Vizro features.
       </p>
     </div>
   </div>
@@ -31,9 +31,9 @@ Vizro is a toolkit for creating modular data visualization applications.
 <a class="card-wrapper" href="pages/API_reference/vizro/">
   <div class="card">
     <div class="card-content">
-      <h5>API reference</h5>
+      <h5>API Reference</h5>
       <p>
-        The API reference contains a detailed description of the Vizro API and our pydantic models.
+        Detailed reference of the Vizro API and our pydantic models.
       </p>
     </div>
   </div>
@@ -44,7 +44,7 @@ Vizro is a toolkit for creating modular data visualization applications.
     <div class="card-content">
       <h5>Explanation</h5>
       <p>
-        Our explanation section contains background information and the answer to "why" questions.
+        Background information and answers to your "why..?" questions.
       </p>
     </div>
   </div>
@@ -55,7 +55,7 @@ Vizro is a toolkit for creating modular data visualization applications.
     <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>

vizro-core/docs/pages/development/authors.md

@@ -1,16 +1,19 @@
 ## Current team members
 
-[Chiara Pullem](https://github.com/chiara-sophie),
-[Antony Milne](https://github.com/antonymilne),
+[Alexey Snigir](https://github.com/l0uden),
 [Anna Xiong](https://github.com/Anna-Xiong),
+[Antony Milne](https://github.com/antonymilne),
+[Chiara Pullem](https://github.com/chiara-sophie),
+[Dan Dumitriu](https://github.com/dandumitriu1),
+[Huong Li Nguyen](https://github.com/huong-li-nguyen),
+[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),
 [Petar Pejovic](https://github.com/petar-qb)
-[Alexey Snigir](https://github.com/l0uden),
-[Maximilian Schulz](https://github.com/maxschulz-COL),
-[Huong Li Nguyen](https://github.com/huong-li-nguyen),
-[Dan Dumitriu](https://github.com/dandumitriu1),
-[Joseph Perkins](https://github.com/Joseph-Perkins),
+
+
 
 ## Previous team members and code contributors
 
@@ -19,7 +22,6 @@
 Natalia Kurakina,
 [Leon Nallamuthu](https://github.com/leonnallamuthu),
 [axa99](https://github.com/axa99),
-[Jo Stichbury](https://github.com/stichbury),
 [Juan Luis Cano Rodríguez](https://github.com/astrojuanlu),
 [Denis Lebedev](https://github.com/DenisLebedevMcK),
 [Qiuyi Chen](https://github.com/Qiuyi-Chen),

vizro-core/docs/pages/development/contributing.md

@@ -2,7 +2,7 @@
 
 Contributions of all experience levels are welcome! There are many ways to contribute, and we appreciate all of them. Please use our [issues page](https://github.com/mckinsey/vizro/issues) to discuss any contributions. Before opening a pull request, please ensure you've first opened an issue to discuss the contribution.
 
-### Found a bug
+### Found a bug?
 
 Great! We would appreciate if you could head to our [issues page](https://github.com/mckinsey/vizro/issues) and raise a ticket in the category `bug report`. It would greatly assist us if you could first check if there are any existing issues with a similar description before submitting a new ticket. We will promptly work on reproducing the bug you've reported and will follow up with the next steps.
 
@@ -67,7 +67,7 @@ hatch run test
 
 To run only python unit tests, run `hatch run test-unit`, and for python integration tests only run `hatch run test-integration`.
 
-For integration tests, all examples are executed in separate testing sessions due to [this](https://github.com/mckinsey/vizro/issues/10) issue by providing the `-k` tag per example.
+For integration tests, [all examples are executed in separate testing sessions](https://github.com/mckinsey/vizro/issues/10) by providing the `-k` tag per example.
 
 Arguments are passed through to the underlying `pytest` command, e.g.
 
@@ -180,7 +180,7 @@ To build the source distribution and wheel, run `hatch build`.
 
 The Vizro team pledges to foster and maintain a friendly community. We enforce a [Code of Conduct](https://github.com/mckinsey/vizro/tree/main/CODE_OF_CONDUCT.md) to ensure every Vizro contributor is welcomed and treated with respect.
 
-## FAQ
+## Frequently asked questions
 
 ### How do I add a dependency?
 

vizro-core/docs/pages/development/documentation-style-guide.md

@@ -94,8 +94,12 @@ This is less helpful:
 
 Don't write this:
 
+<!-- vale off -->
+
 > To learn how to contribute to Vizro, see [here](https://vizro.readthedocs.io/en/stable/pages/development/contributing/).
 
+<!-- vale on -->
+
 ### Internal cross-referencing
 We use internal cross-references as follows:
 

vizro-core/docs/pages/explanation/why-vizro.md

@@ -31,7 +31,7 @@ Users can configure Vizro dashboards without needing to know advanced software d
     This removes most of the "glue code" that would otherwise need to be written. Thousands of lines of code are reduced to tens of lines of configuration.
     Users can configure Vizro dashboards without needing to know any advanced software development principles of how to build front-end applications.
 
-### 2) Extend & customize infinitely
+### 2) Extend and customize infinitely
 
 Users benefit from the power of the Dash framework and the flexibility of React.