Documentation page of the Spezi Ecosystem #118
Conversation
There was a problem hiding this comment.
Thank you for your first contribution @milanagm!
Happy to see better and more clearer documentation around Spezi and the functionalities we provide. I provided a few suggestions thought the PR to point us to a few improvements.
I would generally aim to:
- Use some more visual & links to the relevant documentation/code examples to guide them right to the interesting parts of the relevant modules.
- Ensure that we have a good mixture of written out text & elements that make it a good introduction to newcomers to the ecosystem.
- Ensure that we make this maintainable & extensible in the future by not being too overly specific around version numbers and elements that might change but focus on the high-level concepts of reach module.
- Ensure that we have a general introduction at the beginning about Spezi & the ecosystem to answer some immediate questions people might have & those that you had at the very beginning.
Sources/Spezi/Spezi.docc/Spezi.md
Outdated
| @@ -24,9 +24,13 @@ Unfortunately, DocC currently does not support dark mode images: https://github. | |||
| --> | |||
| @Row { | |||
| @Column { | |||
| @Image(source: "https://raw.githubusercontent.com/StanfordSpezi/SpeziOnboarding/main/Sources/SpeziOnboarding/SpeziOnboarding.docc/Resources/ConsentView.png", alt: "Screenshot displaying the UI of the onboarding module.") { | |||
| @Image(source: "https://raw.githubusercontent.com/StanfordSpezi/SpeziOnboarding/main/Sources/SpeziOnboarding/SpeziOnboardistong.docc/Resources/ConsentView.png", alt: "Screenshot displaying the UI of the onboarding module.") { | |||
There was a problem hiding this comment.
Might be a typo here; probably shouldn't be included in the diff.
Sources/Spezi/Spezi.docc/Spezi.md
Outdated
|
|
||
|
|
||
|
|
||
|
|
There was a problem hiding this comment.
We should generally use the same naming scheme as used for the other files.
| SPDX-License-Identifier: MIT | ||
| --> | ||
|
|
||
| Discover the core modules available in the Spezi framework and understand their use cases. |
There was a problem hiding this comment.
We should aim to unify the usage of ecosystem & framework. I suspect that most of the elements are relating to the ecosystem? Maybe we phrase it more positively, ideally something like: "... and how you can use it to build your applications."
There was a problem hiding this comment.
I adjusted the sentence but i am a bit unsure about your explanation.
| ### Spezi Onboarding | ||
| - **[SpeziOnboarding](https://github.com/StanfordSpezi/SpeziOnboarding)** | ||
| - [SpeziOnboarding Documentation](https://swiftpackageindex.com/StanfordSpezi/SpeziOnboarding/1.2.2/documentation/spezionboarding) | ||
| - Use Case: This module handles user onboarding and initial registration flows. | ||
| - Features: | ||
| - Welcome screen | ||
| - Sequential onboarding screens | ||
| - Consent screen for users to read and agree to documents | ||
| - This module is included and demonstrated in the Template Application. |
There was a problem hiding this comment.
I am wondering if we should use a more visual approach here and ideally also point people to some documentation in the relevant modules, ensuring that we point to some concrete types or relevant documentation articles/overviews in the relevant modules. I would avoid too many bullet points here, maybe only for the key features. Other elements could be transformed into 1-2 liners & some code examples and screenshots or relevant modules.
The initial DocC home page uses the visuals form the other modules to provide a nice overview of the module with one screenshot each. We might want to add tables of 3-4 screenshots from the relevant modules or code examples to highlight the usage of the modules.
I would suggest that we link to a few key types & use cases in the bullet points that detail the features to allow readers to easily jump to a point where they can learn how to implement the relevant feature.
|
|
||
| ### Spezi Onboarding | ||
| - **[SpeziOnboarding](https://github.com/StanfordSpezi/SpeziOnboarding)** | ||
| - [SpeziOnboarding Documentation](https://swiftpackageindex.com/StanfordSpezi/SpeziOnboarding/1.2.2/documentation/spezionboarding) |
There was a problem hiding this comment.
We might want to package these documentation links into nice Tip boxes or something similar that highlights them in the DocC documentation? In addition, I would avoid linking concrete versioned tags, we should always aim to link to the latest documentation (https://swiftpackageindex.com/StanfordSpezi/SpeziOnboarding/1.2.2/documentation/spezionboarding -> https://swiftpackageindex.com/StanfordSpezi/SpeziOnboarding/documentation/spezionboarding). Links without explicit version tags should always point to the latest version.
| The Spezi ecosystem provides a collection of interoperable modules designed to accelerate healthcare and research application development. Each module is built to work independently or in combination with others, allowing you to choose the components that best fit your needs. | ||
|
|
||
| ## Core Modules | ||
| Some of the following modules can be tested and interact with using the Template Application: **[SpeziTemplate](https://github.com/StanfordSpezi/SpeziTemplateApplication)** |
There was a problem hiding this comment.
I would generally suggest embedding links right in the text & flow of the documentation rather then explicitly spelling them out:
| Some of the following modules can be tested and interact with using the Template Application: **[SpeziTemplate](https://github.com/StanfordSpezi/SpeziTemplateApplication)** | |
| Some of the following modules can be tested and interact with using the **[Spezi Template Application](https://github.com/StanfordSpezi/SpeziTemplateApplication)** |
| @@ -87,6 +91,9 @@ You can learn more about modules in the <doc:Module> documentation. | |||
|
|
|||
| ## Topics | |||
|
|
|||
| ### Ecosystem Overview | |||
There was a problem hiding this comment.
We shoulda also aim to incorporate some general documentation on how to get started with Spezi & your learnings of embedding yourself in the ecosystem as part of this PR to help people who are new to the ecosystem to help them answer some clarifying questions.
There was a problem hiding this comment.
Thank you for improving this PR; tagging @vishnuravi and @philippzagar here for a first review; we have been thinking about improvements to the documentation and a first starting guide for a while and can add some first thoughts here 🚀
| - [Spezi Onboarding](#spezi-onboarding) for user onboarding with welcome screens and more. | ||
| - [User Management](#user-management) for login account creation and customization flows. | ||
| - [Spezi Contact](#spezi-contact) for managing and displaying contact information. | ||
| - [Spezi AccessGuard](#spezi-accessguard) for login access codes and biometrics. | ||
| - [Connected Devices and Spezi Bluetooth](#connected-devices-and-spezi-bluetooth) for supporting Bluetooth-connected devices. | ||
| - [Cloud Systems](#cloud-systems) for Google Firebase integration and data synchronization. | ||
| - [Local Data Storage](#local-data-storage) for efficient data persistence and retrieval. | ||
| - [Electronic Health Integration](#electronic-health-integration) for managing FHIR data and data interoperability. | ||
| - [Mobile Health Data](#mobile-health-data) for accessing HealthKit data. | ||
| - [LLMs and AI Integration](#llms-and-ai-integration) for AI-driven functionalities. | ||
| - [Spezi Questionnaire](#spezi-questionnaire) for customizable forms. | ||
| - [Spezi Medication](#spezi-medication) for managing medication details, dosages, and more. | ||
| - [Tasks and Reminders](#tasks-and-reminders) for task scheduling and notification management. | ||
| - [Spezi Notifications](#spezi-notifications) for implementing user notifications and related. |
There was a problem hiding this comment.
Some of the items in this list are names of specific modules (e.g. Spezi Onboarding), and some of them are names of features (e.g. Tasks and Reminders), which is a little confusing. I would either stick to one or the other. What do you think @milanagm @PSchmiedmayer?
There was a problem hiding this comment.
Agree; I would suggest to stick with a generic setup and focus on the currently built out modules that have graduated beyond a 1.0. Anything that currently is not tagged with a 1.0 is not really considered stable and should probably not be listed here.
There was a problem hiding this comment.
Agree, let's keep it to stable (post 1.0) modules (maybe with an exception for e.g. SpeziLLM?), not individual features.
There was a problem hiding this comment.
And we should probably also note down that we only mention our graduated modules here, not "beta" ones
There was a problem hiding this comment.
And: We might order the module list a bit differently, either alphabetically or according to its importance in the Spezi ecosystem? Might also make sense to subdivide that large list with some subheadings that describe the overall topic of a (sub)collection of modules.
| - [Spezi Onboarding](#spezi-onboarding) for user onboarding with welcome screens and more. | ||
| - [User Management](#user-management) for login account creation and customization flows. | ||
| - [Spezi Contact](#spezi-contact) for managing and displaying contact information. | ||
| - [Spezi AccessGuard](#spezi-accessguard) for login access codes and biometrics. | ||
| - [Connected Devices and Spezi Bluetooth](#connected-devices-and-spezi-bluetooth) for supporting Bluetooth-connected devices. | ||
| - [Cloud Systems](#cloud-systems) for Google Firebase integration and data synchronization. | ||
| - [Local Data Storage](#local-data-storage) for efficient data persistence and retrieval. | ||
| - [Electronic Health Integration](#electronic-health-integration) for managing FHIR data and data interoperability. | ||
| - [Mobile Health Data](#mobile-health-data) for accessing HealthKit data. | ||
| - [LLMs and AI Integration](#llms-and-ai-integration) for AI-driven functionalities. | ||
| - [Spezi Questionnaire](#spezi-questionnaire) for customizable forms. | ||
| - [Spezi Medication](#spezi-medication) for managing medication details, dosages, and more. | ||
| - [Tasks and Reminders](#tasks-and-reminders) for task scheduling and notification management. | ||
| - [Spezi Notifications](#spezi-notifications) for implementing user notifications and related. |
There was a problem hiding this comment.
Agree, let's keep it to stable (post 1.0) modules (maybe with an exception for e.g. SpeziLLM?), not individual features.
| - [Spezi Onboarding](#spezi-onboarding) for user onboarding with welcome screens and more. | ||
| - [User Management](#user-management) for login account creation and customization flows. | ||
| - [Spezi Contact](#spezi-contact) for managing and displaying contact information. | ||
| - [Spezi AccessGuard](#spezi-accessguard) for login access codes and biometrics. | ||
| - [Connected Devices and Spezi Bluetooth](#connected-devices-and-spezi-bluetooth) for supporting Bluetooth-connected devices. | ||
| - [Cloud Systems](#cloud-systems) for Google Firebase integration and data synchronization. | ||
| - [Local Data Storage](#local-data-storage) for efficient data persistence and retrieval. | ||
| - [Electronic Health Integration](#electronic-health-integration) for managing FHIR data and data interoperability. | ||
| - [Mobile Health Data](#mobile-health-data) for accessing HealthKit data. | ||
| - [LLMs and AI Integration](#llms-and-ai-integration) for AI-driven functionalities. | ||
| - [Spezi Questionnaire](#spezi-questionnaire) for customizable forms. | ||
| - [Spezi Medication](#spezi-medication) for managing medication details, dosages, and more. | ||
| - [Tasks and Reminders](#tasks-and-reminders) for task scheduling and notification management. | ||
| - [Spezi Notifications](#spezi-notifications) for implementing user notifications and related. |
There was a problem hiding this comment.
And we should probably also note down that we only mention our graduated modules here, not "beta" ones
There was a problem hiding this comment.
We probably need separate .license files here to make the CI pass
| @@ -0,0 +1,50 @@ | |||
| # Spezi Starter Guide | |||
There was a problem hiding this comment.
The content of the starter guide depends a bit on the actual use case. Do you want to just use Spezi modules to build your own health application, fork&contribute to modules, file issues etc.
We should clearly define the target audience for the starter guide. For now, the starter guide is written for future Spezi contributors.
| 1. Access the **[Template Application(#https://github.com/StanfordSpezi/SpeziTemplateApplication)]** here. | ||
|
|
||
| 2. Continue with the **Setup Instructions**: | ||
| - Start by **forking the repository**. |
There was a problem hiding this comment.
We didn't reference the added .pngs yet, right?
There was a problem hiding this comment.
We should definitely reference all added screenshots in the docs
|
|
||
| - Follow the setup and run instructions provided here: [Setup Guide](https://spezi.health/SpeziTemplateApplication/documentation/templateapplication/setup) | ||
|
|
||
| > You may need to update packages, this is how it works best in XCode: |
There was a problem hiding this comment.
I get that updating packages is important but as our template app should be mostly up to date either way, the more important thing would be to show how to add new packages with SPM to the template app. I'm aware that this isn't our doc responsibility and we can just refer to the SPM docs, but for newcomers that might be overwhelming, meaning nice and easy to follow screenshots would be great.
|
|
||
| - If you're ready to work on your first ticket, we recommend checking out the [tickets labeled as "good first issue"](https://github.com/StanfordSpezi/Spezi/issues?q=state%3Aopen%20label%3A%22good%20first%20issue%22), which are specifically designed as starter tasks. | ||
|
|
||
| - Of course, we encourage you to reach out to us directly to discuss potential collaboration opportunities. |
There was a problem hiding this comment.
Should we add a specific contact person or mail (e.g. speziteam@stanford.edu) here? Or is this held vague on purpose?
| - You can explore the current tickets in the [Project Planning Dashboard](https://github.com/orgs/StanfordSpezi/projects/1/views/1) to gain an initial impression of the project's scope. | ||
|
|
||
| - If you're ready to work on your first ticket, we recommend checking out the [tickets labeled as "good first issue"](https://github.com/StanfordSpezi/Spezi/issues?q=state%3Aopen%20label%3A%22good%20first%20issue%22), which are specifically designed as starter tasks. |
There was a problem hiding this comment.
Great links to get started and find tasks! 🚀
Overview of the Spezial Ecosystem
→ prime modules with links to their documentation and use cases
♻️ Current situation & Problem
I worked on the first task of this ticket: #82
⚙️ Release Notes
This documentation is not changing any public interfaces nor any new features.
📚 Documentation
Please ensure that you properly document any additions in conformance to Spezi Documentation Guide.
You can use this section to describe your solution, but we encourage contributors to document your reasoning and changes using in-line documentation.
Not relevant for this PR.
✅ Testing
Please ensure that the PR meets the testing requirements set by CodeCov and that new functionality is appropriately tested.
This section describes important information about the tests and why some elements might not be testable.
Not relevant for this PR.
📝 Code of Conduct & Contributing Guidelines
By submitting creating this pull request, you agree to follow our Code of Conduct and Contributing Guidelines: