Documentation Improvements

[PSchmiedmayer]

Problem

The Template Application should include more structured documentation that takes inspiration from the README but restructures and decomposes the setup into smaller elements.

Solution

This includes:

• Setting up your development environment
  • This includes installing Xcode, Swift, swiftlint, REUSE tool, and more
  • We should automate as much as possible, e.g., reusing elements of https://github.com/StanfordBDHG/ContinousIntegration/blob/main/install.sh.
  • This functionality can be put in the Spezi Template Application, but I am even leaning toward putting it into our Spezi documentation as a "Get Ready with Contributing" or "Developing with Spezi" guide.
  • This documentation might change with each Xcode release, so we should ensure that we use screenshots that are easily replaceable and point to Apple and other documentation as much as possible.
  • Explain how these checks & automated are performed on each PR and why this is beneficial.
• Setup your local Firebase Emulator Environment
  • This includes installing everything and getting started with using the emulator. We should explain the use cases of not using a QA or production system for development, make the setup as easy as possible using a setup script (e.g., reusing elements of https://github.com/StanfordBDHG/ContinousIntegration/blob/main/install.sh).
  • The tutorial should include the importance of maintaining, testing, and updating security rules. We should ensure that we point to the Firebase documentation, if possible, to ensure that any changes in their system don't require us to rewrite the tutorial.
  • We should be mindful that a lot of this documentation should move to the Spezi Firebase Spezi Module and should be linked here.
• Setup your QA or production Firebase environment.
  • Point to the right resources to set up your Firebase environment, and add the right Firebase products and configuration. We should ensure that this documentation is easily extendable when and if we add additional functionality in the Template App.
  • It should include a section on how to change the two main configuration files (.firebaserc and the BUNDLE_ID and PROJECT_ID in the GoogleService-Info.plist)
  • How to administer a services account, provide the minimal scope of permissions (in our case, only write access to the security rules for storage and database), and enable the automated deployment using GitHub Actions.
  • A lot of this documentation should probably move to the Spezi Firebase Swift Package as we want to move the Template Application away from Firebase.
• Setup continuous integration for the template application and TestFlight/AppStore Deployment
  • Explain the need for the different secrets and where and how they are used (see the ContinuousDelivery Example by Paul Schmiedmayer and the Stanford Biodesign Digital Health Template Application as references).
  • Link to Fastlane documentation and additional context about the setup in this repo.
  • Explain how to setup Sign in With Apple for the project. Most of this should probably move to Spezi Firebase and the Account Module in there.
  • Explain the use of GitHub Actions to deploy the application and how this is embedded in the configuration of the application
  • Link to Apple resources on how to change the TestFlight setup, add testers, create a public link, and eventually push the app to the App Store
• How the application is structured and how Spezi is used
  • Explain the usage of the different Spezi Modules in the application, link to the corresponding Spezi and Spezi module docs
  • Explain how to extend the setup in different directions
  • Explain how to use components and modules in your setup and lead off with a suggestion to contribute back to the Spezi ecosystem.

Additional context

It would be great to get community input on these issues, which students and developers are struggling with the most. Please use this issue to discuss the focus area.

Nevertheless, we must ensure we don't reinvent the wheel and set up. We should extensively point to Apple documentation (e.g., https://developer.apple.com/tutorials/app-dev-training/) or Firebase Documentation.
There is no need to re-explain Swift or SwiftUI concepts; we should point to web pages like https://www.hackingwithswift.com/100/swiftui and https://docs.swift.org/swift-book/documentation/the-swift-programming-language/guidedtour/.

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

[PSchmiedmayer]

#59 Addressed a lot of the elements in here but some of the bullet points above need more attention. Good thing is that the infrastructure and hosting for all this is now in place 👍