Making TCA more beginner-friendly

[Jeehut]

When I talk to people about app architecture and they have not had the time or motivation to watch PointFree episodes and lean into testing things out themselves, they often react to me mentioning TCA with something like "yeah, I heard of it, but I prefer to stick to vanilla SwiftUI" or something along the lines of "I'm sure it's cool for larger projects, but it's overkill for me" or sometimes simply "I don't write tests, so why should I use TCA". And that's experienced developers I'm talking about. For people just starting out with iOS or SwiftUI development, I don't see how they could discover and want to learn TCA given how most treat its complexity, instead, they learn MVVM or something else that doesn't really guide them much in their thinking and still leaves most decision as to "where things belong" to them.

In short: TCA is currently viewed as the "gold standard" of app architecture. But it's not viewed as a "go-to standard" yet.

I find this perception a bit sad though. In my opinion, TCA provides a pretty vanilla Swift and SwiftUI approach to app architecture. Yes, it is "opinionated" in mainly one regard: It follows the unidirectional data flow concept where all data is accessible from the root, but scoped to smaller chunks down the line. (I don't consider writing "testable" code to be "opinionated" as I think it's pretty well-known that this is important.) But as I've stated here, I see a lot of potential in exactly this approach to be visualized in a really easy to navigate & explore hierarchical state machine. But more importantly: Apple has designed SwiftUI in a way where unidirectional data flow fits right in. So, in a way, even this "opinionated" decision is pretty "vanilla SwiftUI', filling in the missing "architectural" part lacking in SwiftUI itself.

I also believe that TCA is designed in a way that it's not actually "overkill" for most apps, and even less so with the improvements coming to reducers (currently in beta), which lacked some ergonomy (especially in the pullbacks) and where I could understand the "it's complicated" reaction. But that'll soon be gone and I feel like there's an opportunity here to get everybody onboard who's open to learn something that'll simplify their developer lives.

So, without having some actual plan prepared, I'd like to start the discussion around how we can further make TCA beginner-friendly. I don't know what's lacking in detail, it could be that the library itself isn't the problem, but just the docs needs some improvements. It could be that there's still too much boilerplate needed and a tool simplifying this could help. Or it could also be that there's actually too much stuff in the library itself that is "required" and "enforced" upon us that a more step-by-step adoption path could help.

I don't know, but I feel all the things mentioned need some evaluation at least with the thought of making it more attractive to more developers. Maybe others came across other concerns I didn't mention yet. Please share them.

For me personally, I only started using TCA after I had time to watch the Free Tour videos. But I had seen and starred the library way before that. But the README – while sounding really amazing – also gave me a feeling of "this is complicated". Just look at the very top of it, using advanced terminology like "state management", "composition", "side effects" or "ergonomics".

Beginners – or people who like to write beginner-friendly code – care a lot more about things like "simplicity", "clarity", or "lots of documentation / snippets available". I believe that TCA provides all these, but they are not highlighted as much. So the advanced terminology and too few real-world examples or no step-by-step onboarding or adoption guides were the reason I didn't try TCA out right away. (And I'm not blaming anyone here, of course this needs a lot of work only providable by a larger community.) And this holds true until today: Most of the practical solutions when using TCA I learned by looking at code in the SwifUICaseStudies folder. But I know very few developers who would dive into code examples to learn something new in detail, and it was also a very slow and trial & error approach for me (and still is!).

So for me, a step-by-step practical real-world problems oriented documentation, covering one topic after another, would have been really useful. Something like available for Ruby on Rails, practical advice on different areas that you can learn one at a time. The PointFree video series (even though they are a great learning resource) is more like a "how and why this was built this way and not another" kind of approach, which is great for experienced devs, but not for beginners. And the very well-documented types help with the understanding, but are less practical tips.

The best docs I'm aware of, I just coincidentally discovered while linking the word "well-documented types" in the previous sentence – 4 DocC articles hidden in the "Essentials" section in the documentation, see Getting Started, Getting ready for Swift Concurrency, Performance, and Testing. I couldn't find any links or mentions of these articles in the README though, and this could be an easy first step to improve upon making TCA more beginner-friendly. But it's just a start. I think what's also important is to allow the adoption of TCA in a more gradual manner (which may already be possible!), without having to switch to it all at once – because many devs like to evaluate new tools or patterns before they fully adopt them. A guide (& some library changes) for this, I think, would help a lot. Even if it's just about how to use TCA for just a small portion of an app and stick to "vanilla SwiftUI" everywhere else.

Without having any details, I could also imagine an even more opinionated smaller version of TCA specifically designed for simple cases to onboard newcomers to the general concept of TCA without overwhelming them. (Something like the Microya library I created for the more complex Moya project.) But that's just an idea, maybe it's not even needed & guides + small changes would suffice.

But that's just some input from me to get the discussion started. What are your thoughts on this topic?

[mbrandonw]

Hey @Jeehut, I am about to leave for the airport and I haven't had time to fully read your post, but from what I've read so far I can tell it is very thoughtful. Thank you very much for starting this discussion, and I look forward to what others have to say. @stephencelis and I both know there's a lot more we can do to better communicate TCA and we are eager to improve things!

[Jeehut]

Thank you, that's great to hear. I hope you had a good flight!

Note that I am planning to review the TCA APIs and docs in detail from the perspective of a beginner soon (I just have to finalize my app first) and I plan to make more detailed suggestions on what parts could need some simplification, documentation or gradual adaptability from my perspective. Stay tuned for that.

[sam-mfb]

I think this is an excellent, topic that I have been thinking about as well and would be happy to help out. The iOS version of our enterprise app is entirely built on TCA, and I have a vested interested in more people using and improving the architecture.

A few thoughts:

• There is sometimes a temporal disconnect between the Point-Free episodes that explain the fundamentals of features and then the more "modern" versions of those features. Realizing it's labor intensive, it might be helpful to have places in the episodes that note in the transcript or references where things discussed in the episode have been updated in the current version of the library. This is done sometimes, but not always. I think it would be particularly useful in the Tour of TCA episodes which are free and I assume the entry point for a lot of folks.
• Maybe less of a priority, but I think also useful are pointers the other direction about where to find deeper explanations in the episodes. Just as an example that I happened to come across recently: if you are interested in understanding ways to use ViewStores and ViewStates the explanation of those topics, and things like WithViewStore vs manual binding of stores and creations of ViewState, are spread out in a few different episodes and documentation. Having those links consolidated in the basic documentation on ViewStores might make that easier for folks to find. (And might encourage them to subscribe to Point Free!)
• More generally, I agree with the OP that it might help TCA's adoption if there was a level of documentation that was pitched somewhere between the extremely basic documentation in "Basic Usage", and the much more detailed, but time-consuming and potentially intimidating, understanding you'd get from reading the API spec, watching hours of episodes (which there are other great reasons to do that of course!), and digging through sample apps. I think of it from the perspective of--what would I tell a new developer to read/learn to be able to be conversant in and starting working in TCA in a few weeks (while, of course, still being able to go deeper, and learn more, as they developed their skills)?
• I think a nice example of an approach like this is the Redux Toolkit documentation. IMHO, they do a really nice job of helping people get their feet wet writing code without being intimidated by the power that's under the hood. (They also have a somewhat similar philosophy to TCA, in that it's a more opinionated approach--but still flexible--approach to unidirectional state management than vanilla redux.)

Anyway, interested to see where this discussion goes.

[acosmicflamingo]

I wonder how much Brandon and Stephen feel is left to implement before an official 1.0.0 is released. If tutorials were made a few months ago, they would soon be considered out-of-date because they'd lack the ReduceProtocol, removal of the Environment (with @dependency taking its place), concurrency support, and I think they've set their eyes on navigation functionality next.

But I don't have experience with long-term software development like what they are doing, and it could be that there will always be something that can be improved, in which case it would be good to create tutorials for the current state of TCA.

[cmriboldi]

Yeah, I think that's a really good question. We're on version 0.40.0 without the ReducerProtocol, so it's a good question when is version 1.0.0? So much has changed and improved over the last 2 and a half years since it was released. It's exciting think about.

[sam-mfb]

This is one reason I'd argue documentation like this should be written rather than a video tutorial--it's easier to edit/keep up to date as the code evolves.

[stephencelis]

We think that "navigation" might be the biggest gap in the architecture right now, so once we polish that up it might be time to assess things 😄

[Jeehut]

@stephencelis And "navigation" is the next topic you will focus on next, I guess, based on your recent "just wait to see what's coming next" kind of tweets, right? So it shouldn't be too far away.

The only question is: Will that be enough for 1.0? If Yes, I think it would also be the perfect time for a revised "Tour" video series with all the async + reducer + navigation changes, which together basically change the entire API compared to when the first "Tour" series was produced (even if the basic concept stays the same).

[Jeehut]

I just had the idea of helping beginners TCA beginners (and Pros) by providing a set of Xcode templates to create new Features from with instructions how they can be easily adjusted and installed. I don't currently have the time to play around with this (somewhat hidden) Xcode feature to pull it off in detail, but I found this thread which already seemed to lean on the same idea.

But for beginners specifically, I believe it would be helpful if there was not only a detailed guide how to set them up, but also a variant that looks as similar to vanilla SwiftUI as possible. For example, this variant could prevent the use of WithViewStore which recently learned to be optional - I had always thought it is a different kind of "engine" to make things work. But I learned that the engine is really only SwiftUI itself and TCA only tries to provide "convenience" with WithViewStore - this fact should also be highlighted more prominently to make the TCA examples look more friendly. The downside of having to write more boilerplate code mentioned as a response to my tweet is not there if people use an Xcode template to create their features which can already include the extra initializer.

In my personal opinion, WithViewStore could even be deprecated in favor of using Xcode templates, but that's required to make things more beginner-friendly, it's just my personal preference.

[mfclarke]

Templates are great, but we have found we don't tend to use them now we're more well versed in TCA, on our team. They are a great tool when learning though.

Happy to contribute ours to the repo or put them up externally if anyone would find them useful?

[Jeehut]

@mfclarke Yes, having your template around as an example to steal code/ideas from would be very helpful!

[taskcruncher]

I 100% support making TCA easier for beginners to use. What I love about TCA is that, like Ruby on Rails, it provides a clear, battle-tested outline for how to develop an app. But it's a struggle to learn.

Introduction of Reducer Protocol will help a lot. A lot. Anything else that can be done on the library front to further simplify / reduce boilerplate would be awesome.

Possible ideas for how to make it easier for beginners:

1. The videos are amazing. If you stick with them, you'll learn a lot. But it's almost impossible to onboard using the videos. They are dense. For that reason, I would favor about 50 -- 100 two minute videos aimed 100% at beginners. (Unlike 30 -- 45 minute videos, a two-minute video could be scrapped / edited if key concepts change.)
2. I would leave testing out of all beginner material. This may be controversial. But for beginners trying to learn both coding and testing code in TCA is a steep learning curve.
3. I agree there is a wealth of information in the Case Studies. I'd suggest using a single Case Study for beginners, with the simplest implementation of TCA possible.
4. Move Q+A onto Stackoverflow and off github discussions.
5. Maybe weekly Q+A just for beginners, either video, or from email / github discussions suggestions.
6. Try to find a volunteer(s) to respond quickly to beginner questions on Stackoverflow. Encourage beginners to post using the 'swift-composable-architecture' tag. Foster a 'no stupid question' approach on SO.
7. A beginners 'How-To'. This could follow the beginner's case study. This would use the simplest possible construction of a TCA app, excluding managing Previews and Testing. Just something that compiles and introduces key TCA concepts.

Ultimately, TCA can only be made so simple. It will always take quite a bit of effort to fully internalize.

I've almost given up on TCA a couple of times. Trying to wrestle a zoo of Generics, Reducers, Environments, and Views into a compiling code is not easy at all. It was much worse when nothing in Reducers autocompleted. But intuitively I know TCA is the future of app development on the iOS platform. For that reason I strongly support making it easier for beginners. Big thanks to the PointFree guys. It's an AMAZING library, and it's getting better.

[mfclarke]

I think making TCA more beginner friendly would involve a layer over the top. And then a clear path to go a level down when you need to. Even just a starter project that is set up for hypermodularisation with TCA.

Ruby on rails wasn't entirely beginner friendly at the start. It was the codegen stuff that really opened it up to everyone. Perhaps TCA needs a similar approach for common use cases.

A really opinionated project setup and set of codegen scripts for common feature use cases would go a long way I think.

[mbrandonw]

I just wanted to post a quick follow up to this discussion to let y'all know we have taken some small steps towards making the library more beginner friendly, but there's still a lot more to do.

First, we released 0.41 today, which includes the ReducerProtocol and new dependency management system. Hopefully these tools make the barrier to entry much lower. We have also add a lot more documentation to various types and functions, and all new articles. And we have linked to those articles in the readme.

We have one more big release we want to get out before we consider the library 1.0, and then at that time we can finally explore some of y'alls other ideas such as a brand new tour series of episodes.

Thanks again to everyone for their feedback so far.

[Jeehut]

Thank you guys for all your hard work to constantly improve things, making app development (with SwiftUI) safer and much easier to reason about. Your work is driving the community forward in ways that I think even Apple has to officially honor at some point, and I'm sure they will in one way or another.

I'm particularly thankful today, as TCA helped me keep things organized in the app that I'm about to release today, which is 100% built around TCA. Without it, I'm sure I would either have more logical bugs that are easy to creep in in developer tooling (like this app) or I would still be refactoring things to improve the maintainability of the project, because I tried coming up with my own architecture as I didn't like any others. 😅

I'm really looking forward to helping improve and spreading the word for this library even more once 1.0 is released. Cheers! 🍻

[oliverfoggin]

Just to chip in here. I started my current job a year ago. When I joined the app was in dire need of a lot of improvement. I kept mentioning TCA as something I'd like to implement in the app. The reaction was the same every time, we don't need it, it's overly complicated, etc...

Right now, a year later, we have started making a move on a huge update to the app. When we started it I started with the beta branch of TCA.

When I started to explain how it works to the team and looking at what we had done in a week or so the general reaction from the team was (sarcastically) "This is awesome, why didn't you mention it before?"

The new release does help a lot in making the structure more friendly to beginners.

I think the biggest help to getting people on board was to show them how much easier things were with it than without it. Especially with the new Dependency stuff.