I wanted to add my thoughts to Casey’s post about Apple’s developer documentation which itself stems from a really great episode of Under the Radar. I listened to the same episode and it helped crystallize the friction that I’ve been feeling with the process of learning to use SwiftUI in my work.
When I started learning to build iOS apps in 2010 I learned by reading tutorials and watching videos. At first the only things I knew how to do with a UITableView were the things I read about in tutorials. If I ran into a problem I didn’t know how to solve, I google searched until I found a tutorial that mentioned the name of the delegate method I needed to implement.
Eventually I learned enough of the patterns that iOS frameworks were built around that I realized I could probably just find the answer to my question in the built in documentation and header files. There were some great tools like Ingredients and Dash that helped me find what I wanted, but more often than not I relied on header files to solve my problem.
The beauty of that approach is that you’re always one command click / jump to definition away from discovering an answer. If you see the name of the type you need to learn about, or the signature of a method you have a question about, you can just click on it and start your research. You can see everything that type or method can do laid out in the header file.
I used that approach to learn the Compositional Layout system that Casey mentions. When I wanted to figure out how to make a sticky header in a scrolling list, I could command click through the definitions of a few types until the pinToVisibleBounds property of the NSCollectionLayoutBoundarySupplementaryItem class caught my eye. The answer was there for me to find after spending a few clicks to find it.
That brings us to today and learning to use SwiftUI. The Swift programming language may have gotten rid of the compiler’s need to define a real header file but it didn’t get rid of the programmer’s need to have clear and orderly descriptions of types and what they can do. When I started experimenting with SwiftUI my instinct was to start command clicking on types to learn from their definitions. This time though, command clicking didn't help me. When you jump to the definition of a type in SwiftUI you end up in the 22,000 line definition of SwiftUI itself.
You actually can discover some of the modifiers and important types there that you need to use, but the lack of structural organization and the sheer scope of of the definition file keeps the information feeling like it's trying to hide from you.
I have yet to be able to solve any kind of non-trivial SwiftUI problem on my own inside of Xcode. For every issue I run into I’m falling back to the time-tested practice of google searching for a tutorial that happens to mention the name of a modifier that I need to know. The tutorials and new blogs and websites that I have found have been wonderfully helpful, but I don't believe they should be the only resources I can use to solve problems that I run into while using this framework.
I believe now that this aspect of SwiftUI is the most important issue standing in the way of me adopting it into a greater part of my workflow. I’ve now shipped quite a bit of SwiftUI code in the apps I work on, including in Widgets for iOS 14, but this friction in the process of learning SwiftUI takes away from the experience and doesn’t make me excited to learn more about it. It leaves me feeling like the incredible power of SwiftUI is trapped behind an invisible wall banging to be heard, but I just simply can’t see or hear it as I wander about concerned and trying to find it.