braze-inc / braze-swift-sdk

Braze SDK for the Apple ecosystem, including: iOS, macOS, iPadOS, visionOS, tvOS
https://www.braze.com
Other
52 stars 19 forks source link

[Feature]: Improve migration documentation #70

Closed tsal closed 1 year ago

tsal commented 1 year ago

What problem are you facing?

While migrating our iOS app, there are two paths provided, and it is implied the second path needs the first path / needs some parts of it. That isn't clear. In addition, "In-App Messaging UI" probably needs to spell out that this is for the entire feature because with the notice underneath it, it looks like it's for setting up the UI, which we don't customize.

Workarounds

Reading 3 different documents to get the correct and concise answer.

Ideal Solution

Other Information

Don't take this request badly - the documentation was really good, compared to other "integration" docs from analytics providers, just these two minor issues that caused more confusion than necessary.

hokstuff commented 1 year ago

Hi @tsal,

Thanks for the pointers in our documentation.

Updating the two migration paths to completely decouple them, even if the steps are the same.

I believe you are referencing how steps 1-2 in this section are a short rewording of Scenario 1's section? We'll look into either copy-pasting the relevant content or else an explicit "follow steps X-Y in Scenario 1" to make sure people first read through all of Scenario 1 prior to starting Scenario 2.

Updating the "In-App Messaging UI" heading to be "In-App Messaging" and provide more detail about what is needed -- or just provide the single line of code that is needed in the most basic case.

Are you referencing this section of our migration docs? The highlighted text talks more generally about the In-App Messaging UI itself, and the Tip below discusses extra work needed when performing customization.

I get how it can be confusing, and I think moving the Tip below the Main API changes section should be sufficient. This way, all the content necessary for using In-App Message UI (both default and customized) should be together on the top, and only the customization steps will be below it.

Best, Daniel

tsal commented 1 year ago

Thanks! I think explicitly stating the steps need to be taken would help! And also think moving the Tip section would definitely eliminate any confusion there, too! Thanks!

lowip commented 1 year ago

Hi @tsal,

The documentation has been updated in our last release, thanks again for the feedback!