Documentation Improvements (#23)

* Added workflows to publish documentation and removed as dependencies in poetry * Update README * Update README * Add logo * Fix run command * Add assets * Edit index page cards and why hc section * Edit text and checked working code samples * Add contributing guidelines link * Change pydantic model dump to exclude unset * Remove markdown validation in CDSResponse * Fix timeout issue * Fix tests * README * Removed full example section
dotimplement · Jun 10, 2024 · e838827 · e838827
1 parent c7ab335
commit e838827
Show file tree

Hide file tree

Showing 17 changed files with 298 additions and 488 deletions.
diff --git a/.github/workflows/build_documentation.yml b/.github/workflows/build_documentation.yml
@@ -0,0 +1,22 @@
+name: Build documentation
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+
+      - name: Build the documentation
+        env:
+          GOOGLE_ANALYTICS_TAG: ${{ secrets.GOOGLE_ANALYTICS_TAG }}
+        run: |
+          pip install -r requirements-doc.txt
+          mkdocs build
diff --git a/.github/workflows/deploy_documentation.yml b/.github/workflows/deploy_documentation.yml
@@ -0,0 +1,30 @@
+name: Publish documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install -r requirements-doc.txt
+      - name: Build documentation
+        env:
+          GOOGLE_ANALYTICS_TAG: ${{ secrets.GOOGLE_ANALYTICS_TAG }}
+        run: mkdocs gh-deploy --force
diff --git a/README.md b/README.md
@@ -4,20 +4,24 @@
 
 Simplify prototyping and testing AI/NLP applications in a healthcare context 💫 🏥.
 
-Building applications that integrate in healthcare systems is complex, and so is designing reliable, reactive algorithms involving text and structured data. Let's try to change that.
+Building applications that integrate in healthcare systems is complex, and so is designing reliable, reactive algorithms involving unstructured data. Let's try to change that.
 
 ```bash
 pip install healthchain
 ```
-> 🚧 This is a work in progress with a limited set of functionalities and resources implemented. Things might break. 💥 We are working towards a full release soon! 👀
-
 
 ## Features
 - [x] 🍱 Create sandbox servers and clients that comply with real EHRs API and data standards.
 - [x] 🗃️ Generate synthetic FHIR resources or load your own data as free-text.
 - [x] 💾 Save generated request and response data for each sandbox run.
 - [x] 🎈 Streamlit dashboard to inspect generated data and responses.
-- [x] 🧪 Experiment with LLMs in a fully HL7 standard-compliant pipeline from day 1.
+- [x] 🧪 Experiment with LLMs in an end-to-end HL7-compliant pipeline from day 1.
+
+## Why use HealthChain?
+-  **Scaling EHR integrations is a manual and time-consuming process** - HealthChain abstracts away complexities so you can focus on AI development, not EHR configurations.
+-  **Evaluating the behaviour of AI in complex systems is a difficult and labor-intensive task** - HealthChain provides a framework to test the real-world resilience of your whole system, not just your models.
+-  **[Most healthcare data is unstructured](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6372467/)** - HealthChain is optimised for real-time AI/NLP applications that deal with realistic healthcare data.
+- **Built by health tech developers, for health tech developers** - HealthChain is tech stack agnostic, modular, and easily extensible.
 
 ## Clinical Decision Support (CDS)
 [CDS Hooks](https://cds-hooks.org/) is an [HL7](https://cds-hooks.hl7.org) published specification for clinical decision support.
@@ -62,9 +66,9 @@ if __name__ == "__main__":
 
 Then run:
 ```bash
-healthchain mycds.py
+healthchain run mycds.py
 ```
-This will populate your EHR client with the data generation method you have defined, send requests to your server for processing, and save the data in `./output' by default.
+This will populate your EHR client with the data generation method you have defined, send requests to your server for processing, and save the data in `./output` by default.
 
 ### Streamlit dashboard
 Note this is currently not meant to be a frontend to the EHR client, so you will have to run it separately from the sandbox application.
@@ -74,13 +78,13 @@ streamlit streamlit-demo/app.py
 ```
 
 ## Road Map
-- [ ] 📝 Adding Clinical Documentation use case: CDA data generation, NoteReader API, and structured data extraction applications
-- [ ] 🎛️ Ability to test different EHR backend data configurations in client
-- [ ] 📦 Versioning of configurations and model artifacts
+- [ ] 📝 Adding Clinical Documentation use case
+- [ ] 🎛️ Version and test different EHR backend configurations
+- [ ] 🤖 Integrations with popular LLM and NLP libraries
+- [ ] ❓ Evaluation framework for pipelines and use cases
 - [ ] ✨ Improvements to synthetic data generator methods
-- [ ] 👾 Add proper frontend for EHR client which renders more complex cards
-- [ ] 🐳 Serve with Docker containers
-- [ ] 🚀 Use LLMs to parse configuration and modify integration code
+- [ ] 👾 Frontend demo for EHR client
+- [ ] 🚀 Production deployment options
 
 ## Contribute
 We are always eager to hear feedback and suggestions, especially if you are a developer or researcher working with healthcare systems!

diff --git a/docs/assets/healthchain_logo.png b/docs/assets/healthchain_logo.png
diff --git a/docs/assets/synthetic_data_ons.png b/docs/assets/synthetic_data_ons.png
diff --git a/docs/community/index.md b/docs/community/index.md
@@ -2,4 +2,4 @@
 
 ## Contribute
 
-[Contributing Guidelines](../../CONTRIBUTING.md)
+[Contributing Guidelines](https://github.com/dotimplement/HealthChain/blob/main/CONTRIBUTING.md)
diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,6 @@
-# HealthChain 💫 🏥
+# Welcome to HealthChain
 
-Simplify prototyping and testing AI/NLP applications in a healthcare context.
+HealthChain💫🏥 is an open-source Python package that provides a framework for testing and validating AI/NLP applications in a healthcare context.
 
 [ :fontawesome-brands-discord: Join our Discord](https://discord.gg/jG4UWCUh){ .md-button .md-button--primary }
 
@@ -19,10 +19,18 @@ Simplify prototyping and testing AI/NLP applications in a healthcare context.
 
     ---
 
-    Test LLMs in a full health-context aware pipeline from day 1
+    Test your models in a full health-context aware pipeline from day 1
 
     [:octicons-arrow-right-24: Quickstart](quickstart.md)
 
+-   :octicons-stack-24:{ .lg .middle } __Use Cases__
+
+    ---
+
+    Explore use cases available in HealthChain
+
+    [:octicons-arrow-right-24: Use Cases](usecases.md)
+
 -   :material-lightbulb-on-outline:{ .lg .middle } __Contribute__
 
     ---
@@ -31,12 +39,22 @@ Simplify prototyping and testing AI/NLP applications in a healthcare context.
 
     [:octicons-arrow-right-24: Community](community/index.md)
 
--   :material-scale-balance:{ .lg .middle } __Open Source, Apache 2.0__
 
-    ---
 
-    HealtchChain is licensed under Apache 2.0 and available on [GitHub](https://github.com/dotimplement/HealthChain)
+</div>
+
+## Why HealthChain?
 
-    [:octicons-arrow-right-24: Licence](license-page.md)
+You've probably heard every *AI will revolutionise healthcare* pitch by now, but if you're one of the people who think: wait, can we go beyond just vibe-checking and *actually* build products that are reliable, reactive, and easy to scale in complex healthcare systems? Then HealthChain is probably for you.
 
-</div>
+Specifically, HealthChain addresses two challenges:
+
+1. **Scaling EHR integrations of real-time AI/NLP applications is a manual and time-consuming process.**
+
+2. **Testing and evaluating unstructured data in complex, outcome focused systems is a challenging and labour-intensive task.**
+
+We believe in doing one thing, but doing it well. Building in healthcare is about people, processes, and technology, and we believe there is a need for more robust versioning, validation and testing frameworks for AI models that integrate into EHR systems.
+
+We believe more efficient end-to-end pipeline and integration testing at an early stage in development will give you back time to focus on what actually matters: developing safer, more effective and more explainable models that scale to real-world *adoption*. Building products for healthcare in a process that is *human*-centric.
+
+<!-- HealthChain is made engineers and data scientists with experience in software engineering, machine learning, and NLP. We have worked with integrating real-time AI/NLP systems that have been deployed live at NHS trust sites. -->
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,4 +2,4 @@

		## Contribute

		[Contributing Guidelines](../../CONTRIBUTING.md)
		[Contributing Guidelines](https://github.com/dotimplement/HealthChain/blob/main/CONTRIBUTING.md)