Documentation page of the Spezi Ecosystem

[milanagm]

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:

• I agree to follow the Code of Conduct and Contributing Guidelines.

[PSchmiedmayer]

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.

[PSchmiedmayer]

Might be a typo here; probably shouldn't be included in the diff.

[PSchmiedmayer]

Suggested change

[PSchmiedmayer]

We should generally use the same naming scheme as used for the other files.

[PSchmiedmayer]

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."

[milanagm]

I adjusted the sentence but i am a bit unsure about your explanation.

[PSchmiedmayer]

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.

[PSchmiedmayer]

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.

[PSchmiedmayer]

I would generally suggest embedding links right in the text & flow of the documentation rather then explicitly spelling them out:

Suggested change

	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)**

[PSchmiedmayer]

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.