Merge 276a487 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/community/index.md

@@ -1,3 +1,47 @@
 # Community of Practice
 
-<!-- Something about our CoP here. -->
+Welcome to the Community page of the Trustworthy and Ethical Assurance (TEA) Platform documentation. At the heart of the TEA Platform is a commitment to fostering a vibrant and engaged community of practice. We believe that the challenges of ethical assurance in data-driven technologies are best addressed collaboratively, bringing together diverse perspectives and expertise. Building a community around the platform not only enriches the user experience but also strengthens the integrity and impact of the assurance cases developed through it.
+
+## Building Our Community Infrastructure
+
+We are currently in the process of building out our community infrastructure for the TEA Platform. This includes developing forums, collaborative tools, and resources to support our members in their assurance case work. Our goal is to create a dynamic and supportive environment that facilitates meaningful interactions and collaborations within the community.
+
+!!! example "Join us in shaping the future of ethical assurance"
+
+    We are excited about the potential of the TEA Platform to bring together a community of practitioners passionate about ethical technology governance. If you are interested in talking further about our community development efforts or wish to contribute, please reach out to the Research Application Manager, Kalle Westerling, at kwesterling@turing.ac.uk. We welcome your insights, expertise, and enthusiasm as we work together to build a community that reflects our shared values and goals.
+
+Together, we can build a community that not only advances the field of technology assurance but also ensures that the development and application of data-driven technologies are conducted ethically, transparently, and inclusively.
+
+<!--
+TODO: Enable when we've agreed on the community values
+
+## Our Commitment to Community Values
+
+The TEA Platform is guided by core values that shape our approach to developing a community of practice:
+
+<table>
+    <tr>
+        <td>
+            <span style="color:darkblue; font-weight:700;">👐 Inclusivity</span>: We are committed to <em>making the assurance process accessible</em> to a diverse set of stakeholders, ensuring that technology governance is a collaborative and inclusive endeavor.
+        </td>
+        <td>
+            <span style="color:darkblue; font-weight:700;"> 📖 Transparency</span>: We believe in open communication and clear documentation of assurance cases, <em>enabling stakeholders to understand and trust the ethical foundations</em> of technology projects.
+        </td>
+    </tr>
+    <tr>
+        <td>
+            <span style="color:darkblue; font-weight:700;">💡 Innovation</span>: We are dedicated to continuously pushing the boundaries of what is possible in ethical assurance, <em>developing creative solutions</em> that address the evolving challenges of data-driven technologies.
+        </td>
+        <td>
+            <span style="color:darkblue; font-weight:700;">🤝 Collaboration</span>: We encourage the sharing of knowledge, resources, and best practices, <em>promoting collaborative advancement</em> in the field of technology assurance by fostering a supportive community infrastructure.
+        </td>
+    </tr>
+    <tr>
+        <td>
+            <span style="color:darkblue; font-weight:700;">🛡️ Integrity</span>: We are committed to upholding high <em>standards of honesty and accountability in all our endeavours</em>, aiming that the technologies we help assure are developed with societal benefit in mind.
+        </td>
+        <td>
+        </td>
+    </tr>
+</table>
+-->

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