feat: add quicksight faqs

style: move external links to bottom of pages for easier markdown parsing and link reuse

source/documentation/tools/quicksight/faqs.md

@@ -1,5 +1,11 @@
 # Frequently Asked Questions
 
+## How do I know if I should be able to see a particular table/database/domain in QuickSight?  
+
+Databases and Tables should be available via the `Athena` data source in QuickSight provided that:
+- your Analytical Platform `alpha_user` has access to the data via [the data-engineering-database-access GitHub repository]
+- the data is within one of [the `mojap-derived-table` domains] in Create a Derived Table
+
 ## Can I share the dashboards that I create?
 
 ### For consumers
@@ -8,12 +14,24 @@
 
 ## I’m already a user of another version of QuickSight on the AP, what should I do if:
 
-### I could do all of my work on the new QuickSight (all of my tables are create-a-derived-table tables)
+### I can do all of my work on the new QuickSight (all of my tables are create-a-derived-table tables)
 
 Export dashboards from other versions of QuickSight
 
 Import dashboards into QuickSight via Control Panel
 
 ### I can’t do all of my work on the new QuickSight (some / all of my tables are outside create-a-derived-table)
 
-## SPICE
+## When should I use SPICE?
+
+Importing a dataset into [SPICE] imports the data into memory, rather than querying the data where it lives in S3. Whether to use SPICE or directly query the data is a judgement call, and will likely come down to: 
+- how complex the analysis is
+- the size, format and structure of the underlying data
+- how likely users are to drill down into the dashboards
+- user tolerance for load times while making changes to dashboards
+
+<!-- External links -->
+
+[the `mojap-derived-table` domains]: https://github.com/moj-analytical-services/create-a-derived-table/tree/main/mojap_derived_tables/models
+[the data-engineering-database-access GitHub repository]: https://github.com/moj-analytical-services/data-engineering-database-access/?tab=readme-ov-file#access-to-curated-databases
+[SPICE]: https://docs.aws.amazon.com/quicksight/latest/user/managing-spice-capacity.html

source/documentation/tools/quicksight/getting-started.md

@@ -7,19 +7,21 @@
 
 ### Permissions
 
-You'll need permissions to databases, tables, or domains for datasets produced by Create a Derived Table. These permissions are defined in the data-engineering-database-access repo
-
-> **Q:** How do I know if I should be able to see a particular table/database/domain in QuickSight?  
-
-> **A:** See [What data is on quicksight?](/tools/quicksight/what-data-is-in-quicksight) - TL;DR: databases in the repo that have paths beginning with mojap-derived-tables/prod/models/ in their definitions. (example)
+You'll need permissions to databases, tables, or domains for datasets within [the `mojap-derived-table` domains] produced by [Create a Derived Table](/tools/create-a-derived-table).
+These permissions are defined in [the data-engineering-database-access GitHub repository].
 
 ### Enable QuickSight in Analytical Platform Control Panel
 
-[Raise a support request](https://github.com/ministryofjustice/data-platform-support/issues/new/choose) to enable QuickSight for your user
+[Raise a support request] to enable QuickSight for your user
 
 ## Accessing QuickSight
 
 - Complete [prerequisites](#prerequisites-to-using-quicksight-in-analytical-platform)
-- Navigate to [QuickSight UI within Control Panel](https://controlpanel.services.analytical-platform.service.justice.gov.uk/quicksight/)
+- Navigate to [QuickSight UI within Control Panel]
 - Dashboard to your heart’s content / contractual obligation
 
+<!-- External links -->
+[the `mojap-derived-table` domains]: https://github.com/moj-analytical-services/create-a-derived-table/tree/main/mojap_derived_tables/models
+[the data-engineering-database-access GitHub repository]: https://github.com/moj-analytical-services/data-engineering-database-access/?tab=readme-ov-file#access-to-curated-databases
+[Raise a support request]: https://github.com/ministryofjustice/data-platform-support/issues/new/choose
+[QuickSight UI within Control Panel]: https://controlpanel.services.analytical-platform.service.justice.gov.uk/quicksight/

source/documentation/tools/quicksight/overview.md

@@ -2,12 +2,19 @@
 
 ## What is QuickSight?
 
-QuickSight is a data visualisation service that allows you to create interactive dashboards and reports from data available on the Analytical Platform; straight to your browser, in a reproducible way. All you’ll need to do is connect your data sources and start building your visualizations using QuickSight's interface. QuickSight is packed full of features for analyzing data using various visualization types, so you'll need to get familiar with certain bits of QuickSight functionality. To learn more about QuickSight, take a look at [their documentation](https://docs.aws.amazon.com/quicksight/latest/user/welcome.html). Some of the basics about working with QuickSight in this user guide, but you can also sign up and work through [QuickSight's own examples](https://docs.aws.amazon.com/quicksight/latest/user/quickstart-createanalysis.html).
+QuickSight is a data visualisation service that allows you to create interactive dashboards and reports from data available on the Analytical Platform; straight to your browser, in a reproducible way. All you’ll need to do is connect your data sources and start building your visualizations using QuickSight's interface. QuickSight is packed full of features for analyzing data using various visualization types, so you'll need to get familiar with certain bits of QuickSight functionality. To learn more about QuickSight, take a look at [the aws documentation]. Some of the basics about working with QuickSight in this user guide, but you can also sign up and work through [QuickSight's own examples].
 
 We’re still in beta so we'd love to get some of you using QuickSight to get your feedback to help guide data visualization best practices in the Ministry of Justice and make sure we can continue to improve the user experience.
 
 ## What data is available in QuickSight?
 
-QuickSight is connected to the [`mojap-derived-table` domains](https://github.com/moj-analytical-services/create-a-derived-table/tree/main/mojap_derived_tables/models) published through [Create a Derived Table](/tools/create-a-derived-table). 
+QuickSight is connected to [the `mojap-derived-table` domains] published through [Create a Derived Table](/tools/create-a-derived-table). 
 
-If the output from Create a Derived Table goes to the `mojap_derived_tables/prod/models` path in S3, it should be available in QuickSight.
+If the output from Create a Derived Table goes to the `mojap_derived_tables/prod/models` path in S3, it should be available in QuickSight.
+
+
+<!-- External links -->
+
+[the aws documentation]: https://docs.aws.amazon.com/quicksight/latest/user/welcome.html
+[QuickSight's own examples]: https://docs.aws.amazon.com/quicksight/latest/user/quickstart-createanalysis.html
+[the `mojap-derived-table` domains]: https://github.com/moj-analytical-services/create-a-derived-table/tree/main/mojap_derived_tables/models

source/documentation/tools/quicksight/working-with-quicksight.md

@@ -9,7 +9,7 @@ Datasets are available via the `Athena` data source in QuickSight:
 When adding a new dataset via Athena you'll be prompted for a `Data source name`. 
 This is just a descriptive name for the new data source tile for **you** in **your** QuickSight interface.
 
-Here's the advice [from aws](https://docs.aws.amazon.com/quicksight/latest/user/create-a-data-source.html) about naming your Data source:
+Here's [the advice from aws] about naming your Data source:
 > _This name displays on the Amazon QuickSight list of existing data sources, which is at the bottom of the 'Create a Dataset' view. 
 Use a name that makes it easy to distinguish your data sources from other similar data sources._
 
@@ -19,7 +19,7 @@ Data will be in the default Catalog (`AwsDataCatalog`), and you should only see
 
 Adding a dataset in this way enables you to add a single table at a time.
 
-You'll be asked if you want to 'Import to [SPICE](https://docs.aws.amazon.com/quicksight/latest/user/managing-spice-capacity.html) for quicker analytics'.  
+You'll be asked if you want to 'Import to [SPICE] for quicker analytics'.  
 This imports the data into memory, rather than querying the data where it lives in S3. Whether to use SPICE or directly query the data is a judgement call, and will likely come down to: 
 - how complex the analysis is
 - the size, format and structure of the underlying data
@@ -28,9 +28,16 @@ This imports the data into memory, rather than querying the data where it lives
 
 
 ## External QuickSight resources
-- [aws resources](https://aws.amazon.com/quicksight/resources/)
-- [aws example analysis](https://docs.aws.amazon.com/quicksight/latest/user/example-analysis.html) (dataset requires file upload)
+- [aws resources]
+- [aws example analysis] (_dataset requires file upload_)
 
 ## Publishing Dashboards
 
 ## Sharing Dashboards
+
+<!-- External links -->
+
+[the advice from aws]: https://docs.aws.amazon.com/quicksight/latest/user/create-a-data-source.html
+[SPICE]: https://docs.aws.amazon.com/quicksight/latest/user/managing-spice-capacity.html
+[aws resources]: https://aws.amazon.com/quicksight/resources/
+[aws example analysis]: https://docs.aws.amazon.com/quicksight/latest/user/example-analysis.html