Merge 7f5427e into 02f7c7b

site/docs/community/community-support.md

@@ -0,0 +1,63 @@
+# Community Support
+
+## Using GitHub issues to share TEA cases and seek feedback
+
+GitHub issues are a powerful tool for collaboration and communication within the software development community. Using GitHub issues to share TEA cases and seek feedback is an excellent way to leverage the collective expertise of the community.
+
+When sharing TEA cases on GitHub, leveraging issues can significantly enhance the feedback loop, allowing you to refine and improve your assurance cases with contributions from a wide audience.
+
+Collaborating via GitHub might enhance the quality of your assurance cases. But that's not all: it also fosters a culture of open sharing and continuous improvement within the ethical assurance domain.
+
+This section guides you on how to use GitHub issues effectively to share your TEA cases and seek valuable feedback.
+
+### Creating a GitHub Issue for Sharing a TEA Case
+
+1. **Navigate to Your Repository**: Open the GitHub repository where your TEA case is hosted. [LINK TO SHARE TEA CASES ON GITHUB]
+2. **Open the Issues Tab**: Click on the "Issues" tab near the top of the repository page.
+3. Click the **"New issue"** button to start drafting your issue. Give your issue a clear title that indicates it’s about sharing a TEA case for feedback. In the description, provide context about the assurance case, including its goals, the specific areas where you're seeking feedback, and any particular challenges you're facing.
+4. Include a **direct link to the assurance case file** (preferably the raw file link if it’s in JSON format for easy import) or to the folder containing the case if there are multiple related files.
+5. **Apply relevant labels** to your issue, such as "feedback-wanted", "TEA case", or "help wanted", to make it easily discoverable for contributors interested in those topics.
+
+### Engaging with Feedback
+
+- **Monitor Your Issue**: Stay active and responsive to any comments or feedback provided on your issue. Engaging with contributors not only helps in refining your TEA case but also builds a collaborative community atmosphere.
+- **Addressing Feedback**: Update your TEA case based on the feedback received, if applicable. You can commit changes to your case file and mention the updates in the issue to keep participants informed.
+- **Close the Issue**: Once you've gathered sufficient feedback and made necessary adjustments to your TEA case, thank the contributors for their input and close the issue. You can always open new issues as your case evolves or as new feedback needs arise.
+
+### Best Practices for Using GitHub Issues
+
+- When seeking feedback, **be as specific as possible** about the areas of the TEA case you're looking to improve. This helps contributors provide targeted and useful suggestions.
+- **Consider creating issue templates for sharing TEA cases** if you plan to do this regularly. Templates can help standardize the information you provide, making it easier for others to understand and contribute.
+- **Invite others to contribute** not just by commenting but also by suggesting edits through pull requests if they have significant improvements or corrections to offer.
+
+## TEA Platform Repository Discussions and Issues
+
+The TEA (Trustworthy and Ethical Assurance) platform's repository on GitHub (https://github.com/alan-turing-institute/AssurancePlatform) serves as a central hub for community engagement, feature development, and issue tracking.
+
+It is our aim to make it a vibrant community space where users, developers, and stakeholders can collaborate to enhance the platform's functionality and usability. We want you all to come together to make the platform better for everyone. By engaging in discussions, reporting issues, requesting features, and contributing to the codebase, you play a vital role in the continuous improvement and success of the TEA platform.
+
+***Join us in our mission to advance trustworthy and ethical assurance in technology.***
+
+Below, we discuss how you can actively participate in discussions, report issues, request new features, and contribute to the platform's development.
+
+### Engaging in Discussions
+
+The repository's Issues [LINK] section is an excellent place for initiating discussions on a wide range of topics, including feature requests, bug reports, and general queries about the TEA platform. This section is where you can voice your thoughts and contribute to ongoing conversations, whether you've encountered a technical glitch, have an idea for a new feature that could improve the platform, or simply have a question about how something works.
+
+### Reporting Bugs
+
+If you encounter a problem or an error while using the TEA platform, we encourage you to report it via the repository's Issues section. When reporting a bug, please provide a detailed description of the issue, steps to reproduce the problem, and any relevant screenshots or error messages. This information is invaluable in diagnosing and resolving issues more efficiently.
+
+### Requesting Features
+
+The TEA platform is continually being developed, and user feedback is a crucial driver of this process. If you have an idea for a new feature or an enhancement to an existing one, please share it as a feature request in the Issues section. Describe your proposed feature, its potential benefits, and how it could be implemented within the platform. Community feedback on these proposals can help prioritize development efforts.
+
+### Contributing to the Codebase
+
+For users with programming experience interested in contributing to the TEA platform, the repository contains detailed instructions on how to contribute to the codebase. Whether it's developing new features, fixing bugs, or improving documentation, your contributions are welcome. Here's how you can get started:
+
+**Read the Contribution Guidelines**: Before making any contributions, please review the contribution guidelines provided in the repository. These guidelines cover the process for submitting pull requests, coding standards, and other important practices.
+
+**Set Up Your Development Environment**: The documentation includes instructions for setting up your development environment, allowing you to work on the codebase, test changes, and ensure your contributions align with the platform's overall architecture and design principles.
+
+**Submit a Pull Request**: Once you've made your changes, submit a pull request through GitHub. Your pull request will be reviewed by the platform's maintainers, and feedback or requests for revisions will be communicated through the GitHub interface.

site/docs/guidance/case-builder.md

@@ -0,0 +1,88 @@
+---
+tags:
+  - core elements
+---
+
+# An Introduction to the TEA Case Builder
+
+The Trustworthy and Ethical Assurance Platform is dedicated to simplifying the process of creating, managing, and sharing assurance cases. Our Assurance Case Builder is a core feature of the platform, designed to help you visually and logically structure your assurance cases with ease.
+
+By following the steps outlined in this section to add goals, contexts, claims, evidence, and strategies, you can effectively articulate and visualize the ethical assurance of your technology projects.
+
+Remember, a well-constructed assurance case not only supports internal review and decision-making but also enhances trust and transparency with external stakeholders. Used correctly, the Case Builder can be a powerful tool that enables you to methodically demonstrate your technology's compliance with ethical standards.
+
+## Adding Elements
+
+To begin, ensure you're logged into the TEA platform and have selected the assurance case you wish to work on. If you're creating a new case, start by naming your case and providing a brief description.
+
+1. **Adding the Goal Element**. In the Assurance Case Builder interface, start by identifying the top-level goal for your case. Click on the "Add Goal" button to create a new goal.
+
+2. **Define the Goal**. Enter a name and a brief description of your goal. This could be a broad ethical aim like "Ensure Data Privacy" or "Achieve Fairness in AI Decision-Making."
+
+   There's no need for you to save as saving happens automatically in the TEA platform. You can simply move on with the next element.
+
+### Incorporating Contexts
+
+Contexts specify the environment or conditions under which the goal applies.
+
+1. **Select Your Goal**. With your goal created, you can add a context. Click on the goal element to bring up the option to add context.
+
+2. **Add Context**. Click on "Add Context" and fill in the details, such as the operational environment or specific user considerations relevant to your goal.
+
+   Again, there's no need for you to save as saving happens automatically.
+
+### Creating Claims
+
+Claims are specific assertions that support your goal within its context.
+
+1. **Choose a Goal or Strategy**. Select either a goal or a strategy (see below) to which you want to attach a claim.
+
+2. **Add a Claim**. Click on "Add Claim" and provide a concise statement that you plan to justify through evidence. For example, "The system encrypts all user data."
+
+3. **Detail Your Claim**. You may also add a longer description if necessary. Again, your claim will be saved automatically.
+
+### Adding Evidence
+
+Evidence can be anything that supports your claim: test results, expert analysis, or compliance certificates.
+
+1. **Select a Claim**. Navigate to the claim for which you have supporting evidence.
+
+2. **Attach Evidence**. Click "Add Evidence" and describe the evidence that supports your claim.
+
+3. **Link to Documentation (Optional)**. If applicable, you can also provide a URL to where the evidence can be found or reviewed. For transparency and accountability reasons, we encourage you to add a URL, but it's not necessary.
+
+   Again, there's no need for you to save as saving happens automatically.
+
+### Utilizing Strategies (Optional)
+
+For complex assurance cases, you may need to outline strategies that describe how you plan to achieve your goals through a series of claims.
+
+1. **Select a Goal**. Choose the goal for which you want to define a strategy.
+
+2. **Define the Strategy**. Click on "Add Strategy" and enter details about how you intend to structure your argument or the approach to meet the goal.
+
+3. **Create Any Claims**. Create any claims for how you will know that you have successfully accomplished the strategic steps.
+
+4. **Attach Evidence to Strategy Claims**: Link existing evidence (or add new evidence) to your strategy's claims to demonstrate how each contributes to achieving the overarching goal.
+
+## Updating Elements
+
+This is a quick guide on how to update elements such as Goals, Contexts, Claims, and Evidence within the Assurance Case Builder.
+
+Updating elements in the TEA Assurance Case Builder is designed to be intuitive, ensuring that your assurance case remains a dynamic and accurate reflection of your project's commitment to ethical standards.
+
+You should always refine and adjust the details of your assurance case as your project evolves or as new information becomes available.
+
+### Steps to Update Elements
+
+1. **Select the Element**. Navigate to the element you wish to update within your assurance case. Elements can be Goals, Contexts, Claims, or Evidence.
+
+2. **Make Your Changes**. In the editing mode, you can modify any of the element's details, such as its name, description, or associated links. For evidence elements, this may include updating URLs or descriptions to reflect the most current documentation.
+
+There's no need to save your work as the platform will automatically save any changes made.
+
+### Tips for Updating Elements
+
+- **Regularly review your assurance case elements** to ensure they remain accurate and relevant throughout the lifecycle of your project.
+- When updating elements, **ensure consistency** in terminology and detail level across your assurance case to facilitate clear understanding and communication.
+- Consider keeping a **log of significant updates** for internal records, especially for elements that impact regulatory compliance or critical ethical considerations. <!-- TODO: For discussion with Chris: this might be a feature that we should even add to the project... -->

site/docs/guidance/case-management.md

@@ -0,0 +1,36 @@
+---
+tags:
+  - core elements
+---
+
+# Managing TEA Assurance Cases
+
+## Using templates and patterns
+
+Importing templates and patterns can significantly accelerate the development of your assurance cases, providing a solid foundation built on industry best practices. Whether you're new to assurance case development or an experienced practitioner, these resources are designed to enhance the quality and efficacy of your ethical assurance efforts.
+
+This guide is designed to streamline your experience in leveraging pre-defined templates and patterns for creating and managing assurance cases. By importing templates and patterns, you can jumpstart the development of your assurance cases, ensuring you adhere to best practices and standards from the outset.
+
+Templates and patterns are foundational tools within the TEA platform, providing structured outlines that encapsulate best practices for assurance case development. These resources are invaluable for users seeking to ensure their technology projects meet ethical, legal, and social standards.
+
+Templates are pre-designed frameworks for assurance cases that outline the basic structure, including goals, claims, contexts, and evidence placeholders.
+
+Only one template is currently built into the platform: the "Minimal" template. This template contains a pre-organised view featuring a Goal, its Context, and a Claim. This setup serves as an intuitive starting point, guiding users through the initial phases of assurance case development with a clear, manageable structure.
+
+However, if you want to access other templates, you can consult the TEA repository where you will find more worked examples and templates that you can import via the Import File feature <!-- TODO: ADD LINK -->.
+
+### Using the Minimal template
+
+1. Navigate to the Dashboard (make sure you are logged in)
+2. If you want to use the built-in template ("Minimal"), click the "Create a new case" button. In the dialog, fill in a Title and a Description, press "Continue". On the next page, select "Minimal" and press "Continue".
+3. Your case should now be set up with the minimal template.
+
+### Using a template from the TEA repository
+
+1. Navigate to the <!-- TODO: ADD A PAGE ON DOCS EXPLAINING THE DIFFERENT TEMPLATES --> and select a template. Click on the "Copy URL" button next to the template you want to use.
+2. Navigate to the Dashboard (make sure you are logged in)
+3. Press the "Import File" button.
+4. Press the "URL upload" radio button.
+5. Paste the URL you copied from the documentation here. (e.g. https://github.com/alan-turing-institute/AssurancePlatform/raw/adding-more-docs/worked-examples/tea-dh/json/5.1.json)
+6. Press "Continue"
+7. Your template should now have loaded in the Case Builder

site/docs/guidance/exporting.md

@@ -0,0 +1,34 @@
+# Exporting TEA Cases
+
+Exporting your TEA cases is a straightforward process designed to facilitate the sharing and archiving of your assurance work.
+
+Exporting your assurance cases from the TEA platform allows you to share your work with stakeholders, archive your cases, or simply keep a local copy for your records. The platform supports exporting cases in two different formats.
+
+By following the simple steps in this guide, you can communicate your commitment to ethical technology development and assurance to all relevant stakeholders.
+
+## Step-by-step Guide
+
+### Step 1: Select Your Case
+
+- Navigate to the dashboard of the TEA platform and locate the assurance case you wish to export.
+- Open the assurance case to access the detailed view.
+
+### Step 2: Choose Export Option
+
+- Look for the “Export” button or in the case view. It is located in the menu that appears if you press the three dots that appear next to the title of your case.
+- Click on “Export” to see the available format options.
+
+### Step 3: Select Format
+
+- The TEA platform offers two formats for export and data interchange: JSON and SVG. Choose the format that best suits your needs.
+
+### Step 4: Download the File
+
+- After selecting the format, initiate the export process. The platform will prepare the file for download.
+- Once the file is ready, you may be prompted to confirm the download or it might start automatically. Ensure you save the file in your desired location.
+
+## Tips for Exporting Cases
+
+- Quickly **review your assurance case** for completeness and accuracy before exporting. Make any necessary updates to ensure the exported document accurately reflects your case.
+- Consider **exporting your assurance cases periodically** to create backups and document the evolution of your assurance arguments over time.
+- When sharing exported cases with stakeholders, **be mindful of sensitive information** and ensure your sharing method complies with data protection regulations.

site/docs/guidance/getting-started.md

@@ -0,0 +1,37 @@
+---
+status: draft
+tags:
+  - Introductory Resource
+---
+
+# Quickly Getting Started with the TEA Platform
+
+Getting started with the Trustworthy and Ethical Assurance (TEA) Platform is a straightforward process designed to get you up and running with creating, managing, and sharing assurance cases in no time. Follow these simple steps to begin your journey towards more transparent and ethical technology assurance.
+
+## Step 1: Sign Up or Log In
+
+Visit the TEA Platform's homepage and locate the "Sign Up" or "Log In" buttons. If you're a new user, you'll need to register for an account using the "Sign Up" feature. Existing users can enter their credentials to log in.
+
+<!-- Screenshot Needed: Homepage with highlighted "Sign Up" and "Log In" buttons. -->
+
+## Step 2: Familiarise Yourself with the Dashboard
+
+Once logged in, you'll be greeted by the dashboard. This is your central hub for accessing all features of the TEA Platform, including creating new assurance cases, viewing existing ones, and accessing educational resources.
+
+## Step 3: Creating a New Assurance Case
+
+To create a new assurance case, click on the "Create a new case" button from the dashboard. You'll be prompted to enter details such as the case name and description. Fill out the necessary fields and submit to create your case.
+
+<!-- Screenshot Needed: The "Create a New Case" interface with form fields and the "Create" button. -->
+
+## Step 4: Building Your Assurance Case
+
+With your assurance case created, it's time to start adding elements like Goals, Contexts, and Evidence. The TEA Platform's intuitive interface allows you to build your assurance case visually.
+
+<!-- Screenshot Needed: The assurance case builder interface, showing how to add and arrange different elements within a case. -->
+
+## Step 4: Exporting and Publishing Your Work
+
+Once you're satisfied with your assurance case, you can export it in various formats for external review or publication. The platform supports exporting to formats like JSON for data exchange or SVG for visual representation.
+
+<!-- Screenshot Needed: The export options menu, showing different file format options available for exporting your assurance case. -->

site/docs/guidance/index.md

@@ -1,7 +1,5 @@
 ---
 status: draft
-tags:
-  - Introductory Resource
 ---
 
 !!! warning "Draft"
@@ -11,9 +9,10 @@ tags:
 In this section you will find the main documentation and user guidance for the TEA platform.
 For those who are completely new to the platform, we recommend you follow these guides in order <!-- (or watch our [introductory video]()) -->:
 
-1. Getting started with the TEA platform (*in progress*)
-2. Building an assurance case (*in progress*)
+1. [Quickly Getting Started with the TEA Platform](getting-started.md) (*in progress*)
+2. [An Introduction to the TEA Case Builder](case-builder.md) (*in progress*)
 3. [Components of an assurance case](components.md)
-4. Managing and sharing assurance cases (*in progress*)
+4. [Managing TEA Assurance Cases](case-management.md) (*in progress*)
+5. [Exporting TEA Cases](exporting.md) (*in progress*)
 
 You can also find more advanced documentation (e.g. deployment instructions, API documentation) in our [platform details](../platform-details/about.md) section.