[Feat] Add Examples directory to provide Case Studies

[DandyLyons]

Problem Statement

Given that the library enables and advocates for new best practices in Swift error handling, I think it would be a good idea to provide examples of how the tools can be used in real-life scenarios.

Suggested Solution

We could provide an Examples directory to hold small projects that demonstrate usage of core features in the library. We can also link to these examples in the docs. This approach has been used extensively in libraries like this.

I recommend starting with an example of using error chain debugging as this is a pattern that is not widely known by the Swift community.

Future Opportunities

(These examples could also double as testing infrastructure.)

[Jeehut]

@DandyLyons That's a great suggestion, I think it makes a lot of sense to improve documentation with code examples. I'm not sure if we really need the level of samples as in the TCA framework you've linked to. That framework is about app architecture and therefore affects all levels of your application, therefore is a very complex library that is trying to be the foundation of your app. ErrorKit on the other hand is lightweight and works as a drop-in replacement to the Error protocol and can be adopted progressively. There's no "you have to use this everywhere in your application to profit" kind of thing, although for error chains, you would need that to some extent.

But I doubt we need too many examples, so while I agree that we could use more code examples just to be even better documented (especially for the error chain feature), I'm not sure if we need full app samples like TCA. Maybe some Playgrounds or dedicated sample articles / tutorials would also do. But a small sample project won't hurt either, so feel free to provide one. Maybe I'll extract some code from some of my production apps at some point to contribute as a sample project.

Let me know if you would like to create a sample project!

[DandyLyons]

Sure. I'd like to create a sample project. I completely agree. TCA's samples are more in-depth than ErrorKit needs. I mostly think the sample would be helpful for chain errors. Just enough to demonstrate how errors can bubble up across multiple systems and yet still retain enough context for the catcher to know who the original thrower was and how to handle the error.

[Jeehut]

@DandyLyons That makes a lot of sense. But please note that "across multiple systems" really sounds like it's only for large apps, I prefer talking about "layers of an app" because basically every app has a UI layer, a model layer, and a business layer. There can be more layers in larger apps, but even in a Hello World application we could demonstrate the layers by just adding a simple network call. It starts to become more clear how useful it is if there are multiple places in the UI, for example, that can cause the same network error. Because then, the error chain gives the UI context where the user tried to do something. Maybe something simple like that could be a first iteration. But feel free to provide something else if you have a better idea!

[DandyLyons]

For the sake of defining scope of an example, I'd like to clarify what is currently supported/not supported.

Initially I'd like to focus on an example demonstrating Error chain debugging since I think that this is a killer feature of the library, it's something that I haven't seen used outside this library and to take full advantage of it requires multiple pieces working together. All of that makes it well suited to be demonstrated in an example project.

Scoping

It seems that I'd like to demonstrate two use cases:

1. Logging an error chain (useful for devs)
2. Presenting an error chain to app users (hopefully this could provide more context to users, which might help them to troubleshoot their problem).

Logging an Error chain

I feel like this use case is pretty well described here, and I can use the same or similar example in the Example directory.

Presenting an error chain to app users

The docs say that errorChainDescription(for error: any Error) is specifically designed for devs, not end users, which makes sense.

If I'm not mistaken, the library does not yet seem to have a great tool for this use case. Am I correct in this understanding? If so, I can put that example use case to rest unless the situation changes.

FWIW, as an end user, what I'd be interested in from an app is the ability to know:

1. What went wrong (how does this affect me).
2. what was the root cause (how can I fix this).

Without an error chain, an app is usually forced to provide only one or the other. For example, I could push a button to submit a post. Then the app could give me an error alert saying "Failed to post comment. Please try again." That tells me what went wrong, but isn't very helpful for telling me what I must do. Or the app could say "Network error." This tells me the cause but doesn't tell me which of my requests failed. So as an end user, I don't know how far back this network error caused other errors.

Error chain debugging has the potential to solve this problem because the error can preserve the greater context. But it seems like there's not yet a tailor-made solution for that specific use case. Does userFriendlyMessage(for error: any Error) have support yet for error chains?

[Jeehut]

@DandyLyons The errorChainDescription function could of course be used to present to users, if that's what you want. Nothing speaks against it. I personally thought about it more like "this is too much info for the user", as it's usually technical internal types that you see there. Most users wouldn't find that helpful, but depending on your app and your target group, you could opt to use it, of course.

A more useful way I have already thought about is to add support for presenting logs to users in a bit more readable way with a nice SwiftUI view. That could be a feature built-in to ErrorKit, with some nice filters that allow you to define what kind of content they see. And that view could somehow include the errorChainDescription because that's what I recommend you to log anyway.

[DandyLyons]

Completely agree. errorChainDescription is "too much info for the user". I'll leave it out of the examples. We can always explore that later.

It sounds like a user facing, error chain aware feature is beyond the scope of this Issue, so I can move that discussion to another issue.

Side note: I think a user facing, error chain aware feature could benefit from progressive disclosure of information. By default it would be userFriendlyMessage. But the user has the option to show more information if they choose. Also, I'd like the ability to provide helpful user tips if a particular error type is anywhere in the chain. For example if NetworkError.noInternet is anywhere in the chain then I can surface a user facing message telling the user that they do not have internet connection.