8 ms·
I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here
by wlesieutre 6y ago
I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!”
Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me.
So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medium posts because something from before WWDC 2020 might no longer be useful. Or maybe it is. How do you know if the feature changed significantly in the more recent release? I don’t know, but I can tell you where you won’t find out: the official docs.
- wlesieutre 6y agoI will say that the WWDC sessions are well presented, and are a good place to start. But you can't use a video for quick reference, and you might be missing context from knowing how it worked the previous year to understand what the new enhancements are. Expect to dig into 2019 videos too. SwiftUI being new at least has the benefit that its sessions can't be any more outdated than that (yet). At most you're reconciling two years. The Landmarks tutorial is also very well done as a starting point. But a tutorial isn't a substitute for documentation. https://developer.apple.com/tutorials/swiftui/ https://developer.apple.com/tutorials/swiftui/
- pornel 6y agoI hate that WWDC videos have essentially replaced docs. Videos have to be shallow, and code on slides has to be short. This medium is fine to sell an idea, and to give a high-level overview of how it works, but there's no way to include as much information as written documentation would. Here's a TED talk on Thorium reactors. Why aren't you running them yet?
- njhaveri 6y agoI also really dislike that WWDC videos are now the de-facto documentation. It must be a lot of work to put them together – I wish they'd just write a doc instead. Would be way faster to read, search, etc. and could probably go into much greater depth.
- andromeduck 6y agoExample programs would be nice too.
- sixstringtheory 6y agoMany of them do come with sample code, but like the content of the sessions themselves, they age out very quickly.
- an_opabinia 6y agoYeah but on the other hand, I'm sure they look at the vibrant 3rd party tutorial content pipeline as evidence that they're doing the right thing.
- Austin_Conlon 6y agoGlobal search for all WWDC transcripts also isn't good on the website, you now how to reveal the transcript for each individual result after you search. In the Apple Developer app (where I would've expected a better user experience) it's not even possible.
- wool_gather 6y agoTry out https://asciiwwdc.com https://asciiwwdc.com next time you need this.
- pak9rabid 6y agoFor all the hate it gets, I think the way PHP does their documentation is ideal. Easy to search for what you need, it recommends other, similar classes/functions, gives a good description of the inputs and what something is expected to return. Then, in addition to that, there's the user-supplied examples and commentary to help further clarify things. I really like the model they went with.
- wizzwizz4 6y agoI concur. PHP is a horrible language, but I don't hate working in it. The documentation is the reason.
- ljm 6y agoI concur and add that PHP has actually evolved quite nicely, and it's horribleness is merely an outdated meme. Java is still playing catchup to the stuff PHP has added in recent years. Just because it was shit 15 years ago doesn't mean it's still shit now.
- tonyjstark 6y agoIMHO there are still some edges that drive you mad until you remember them but the documentation is really good and every release is full of improvements. Also many available frameworks and tools in PHP world are outstanding. For me PHP provides a serious Rapid to Market Edge.
- Phrodo_00 6y agois the PHP standard library still an inconsistent mess?
- geerlingguy 6y agoThe inconsistencies are either fully removed (many in 7.x, more in 8.x), deprecated, or at least very well documented these days (e.g. with top level documentation warnings about any potential pitfalls).
- yoz-y 6y agoOn top of that they often contain pre-first-beta information so they are rapidly obsolete. Although the gist of the information is useful, the signatures and examples are not.
- Cthulhu_ 6y agoSame; there's so much important information in the WWDC videos, and part of me wanted to watch them all when I was still doing iOS development. But I can't watch videos, I don't have the attention span, and sitting to watch / listen just makes me go to sleep. It's a me thing, not down to the presenters or anything. But all that I ask is documentation and / or blog posts. I hope that anyone that is making a presentation also writes down the contents as a blog post and/or documentation. Please. For examples, Go's blog is pretty good (although there too one is often pointed at a presentation or slide deck for certain subjects)
- plorkyeran 6y agoI don't really consider most WWDC videos documentation. They're usually just marketing videos which show off the new features. Even the more in depth videos are rarely more than a shallow introduction.
- jonhendry18 6y agoUnfortunately there's bits of information that are important and only ever appear in the WWDC videos.
- plorkyeran 6y agoThere's also a lot of useful information that has only ever appeared in Twitter conversations between Apple developers but I wouldn't call that documentation either.
- deleted 6y ago[deleted]
- elpakal 6y agoThey have an `API Changes: Hide/Show` thing on their documentation (on the right, top) that I think is new fwiw. https://developer.apple.com/documentation/swiftui/progressview?changes=latest_major https://developer.apple.com/documentation/swiftui/progressvi...
- ChrisMarshallNY 6y agoSwiftUI's docs are a nightmare. Here's a pretty damn cool app: https://swiftui-lab.com https://swiftui-lab.com
- wlesieutre 6y agoExcellent, thanks for this! Most recent post is "Attributed Strings with SwiftUI" which is something I was wondering about. There's plaintext TextEditor view, but for rich text editing the impression I've gotten is to either fall back to something in UIKit or do it in a WebView. Will check this post out tonight, it might not change anything but I'd at least like a better idea where things stand in SwiftUI. Props to Apple on this one, TextEditor has a real docs page. But it's only for plain text, sadly: https://developer.apple.com/documentation/swiftui/texteditor https://developer.apple.com/documentation/swiftui/texteditor
- terhechte 6y agoYeah, for rich text you need to wrap a UITextView, there's currently no other way to do that. Also, if you have a large amount of text, TextEditor won't cut it either. Even displaying rich text (non editable) is a wee bit tricky and severely under documented.
- lukeh 6y agoYeah, the sizing thing is a bit of a pain as the creates visible content fitting artefacts when contained in a list or stack.
- jamil7 6y agoFor a small app I recently just wrapped SlateJS in a webview and passed json back and forth. Slate is pretty nice but it would be nice to use a native solution.
- mhh__ 6y agoHow does it compare to Unreal's, I wonder. Seems to have the same problem, third party (Video, bleugh) tutorials.
- deleted 6y ago[deleted]
- tonyjstark 6y agoI wholeheartedly agree. The documentation is sparse and 3rd party tutorials have to be recent. That's why I still hold back for adoption. Paul Hudson has really good material but I wish I could just leave a tab open with the official documentation and be prepared for most challenges. OTOH, things like Core Audio where never really well documented. For learning Swift I recommend https://www.swiftforgood.com https://www.swiftforgood.com, no affiliation (also there Paul Hudson wrote the chapter about SwiftUI).
- xbar 6y agoAgreed. Great content. Of course, there is no excuse for Apple's chronic underinvestment in Documentation.
- krtkush 6y ago> and always looking at dates on Medium posts While I'm not an iOS dev I have seen a trend where people have stopped putting in dates of their coding tutorials.
- ProAm 6y ago> So instead you end up on 3rd party tutorials...How do you know if the feature changed significantly in the more recent release? I don’t know, but I can tell you where you won’t find out: the official docs. Get ready for documentation subscriptions. I wish I were joking.
- mrtksn 6y agoThat actually sounds good. When you pay for something it implies that you might stop paying for the thing if you’re not happy which means the seller is likely to work hard to make you happy. I would love to have paid version of most of the apps/sites I use. Not ad-free subscription but paid version where I can be the unhappy customer when I am unhappy.
- grp000 6y agoThat would make sense if documentation were a standalone product, but it's completely complementary to the language, so that doesn't make any sense.
- Ronsenshi 6y agoAlready a thing: https://apps.apple.com/us/app/a-companion-for-swiftui/id1485436674?mt=12 https://apps.apple.com/us/app/a-companion-for-swiftui/id1485... No affiliation. It's sad and a bit pathetic that trillion dollar company can't hire even one person to work on public documentation.
- doyouevensunbro 6y agoIt’s because engineers don’t want to write documentation, and if you don’t force it this is the result.
- piva00 6y agoA trillion dollar company should be able to hire some technical writers to embed into teams and write documentation as part of the process. It's just a lack of care when you have that amount of money.
- lostcolony 6y agoI've run into this more often than I can count with Java based things. "Just look at the Javadocs!" You...you mean the auto-generated API descriptors that have exactly zero usage information on them, and expect me to figure out how to piece things together just by type signature? That...that isn't how documentation works.
- grimjack00 6y agoYou mean you can't figure things out from "public Session getSession(String, String, String, String, String)"?
- andi999 6y agoWe tried to buy some mechanical equipment which can be steered by a computer API. I asked for the doc beforehand. Got something like your example (10 pages of C header). I asked any better docs? Answer:'a real programmer would know how to use this' - well somehow they didnt manage to sell the device to us. Later they managed to email the comprehensive docs (which existed!), but we alread spent a much larger amount (without regrets) to the competition.
- wlesieutre 6y agoOn the SwiftUI side, you might go digging in these docs for Previews, which are one of its biggest selling points: https://developer.apple.com/documentation/swiftui/previews https://developer.apple.com/documentation/swiftui/previews Take 30 seconds to read through that and the linked pages (that's all the time it will take) and see if you could figure out how to use a PreviewDevice to make your preview show a particular device. It will tell you all the ways to initialize a PreviewDevice struct (from many different varieties of String), but you'll have no fucking idea what to do with that object. And here's an actual code sample, via Paul Hudson: struct ContentView_Previews: PreviewProvider { static var previews: some View { Group { ContentView() .previewDevice(PreviewDevice(rawValue: "iPhone SE")) .previewDisplayName("iPhone SE") ContentView() .previewDevice(PreviewDevice(rawValue: "iPhone XS Max")) .previewDisplayName("iPhone XS Max") } } } It turns out what you need to do is pass the PreviewDevice instance into a previewDevice modifier that you've applied to your view inside a struct adhering to the PreviewProvider protocol. I don't think this docs page even mentions that the previewDevice modifier exists, let alone how to put any of these pieces together to configure and display a preview. You can find how to do this in tutorials elsewhere on Apple's site. But you can't find it in their documentation for Previews, because it's a bunch of automatically generated pages of function signatures with no explanation.
- Austin_Conlon 6y agoIt needs to have more conceptual articles with code listings like this https://developer.apple.com/documentation/swiftui/managing-model-data-in-your-app https://developer.apple.com/documentation/swiftui/managing-m....
- wlesieutre 6y agoYes please. Finding a “see also” link to one of those is the best, because you know it will actually show you how to use it. Otherwise you’re probably on your own. For example, Previews are one of SwiftUI’s major features. Here’s its docs page: https://developer.apple.com/documentation/swiftui/previews https://developer.apple.com/documentation/swiftui/previews You could read through that and all of the linked pages and still have no idea how create a preview. Want to preview it on a particular device? Well, I can see there’s a PreviewDevice, it’s initialized from various kinds of strings, and absolutely no information on how to apply it. Turns out this is a SwiftUI modifier that you chain off of your view inside the struct that adheres to the PreviewProvider protocol. See example here: https://www.hackingwithswift.com/quick-start/swiftui/how-to-preview-your-layout-in-different-devices https://www.hackingwithswift.com/quick-start/swiftui/how-to-... Could you construct that example from having read the documentation? I doubt it.
- on_and_off 6y agostupid question : but is there any specific reason why swiftui is not open source ? I am working with jetpack compose these days and it is both open source and documented. I am not sure how I would work with it without that, it is quite a big departure from the legacy ui api.
- saagarjha 6y agoProbably because it’s a competitive advantage for Apple to keep to themselves.
- on_and_off 6y agoI wonder how much of an advantage it is practice ? It is one such toolkit among others, like React or Compose. It is different from making the whole OS open source. I guess that since the benefit would be to make third party devs job easier, the incentive is not that great for apple .. devs will write mobile apps even if they have to write them in assembly.
- heavyset_go 6y agoApple figures developers will still pay them $99/year even if they provide them with poor documentation, and unfortunately, it looks like they're right.
- leptons 6y agoMicrosoft: Developers! Developers! Developers! Apple: Fuck off Developers!
- sk5t 6y agoApple: There's no official documentation for this, but here's a haughty forum response from an unaffiliated volunteer sycophant directing you to the extant superficially-related documentation.
- JAlexoid 6y agoSince developers are no longer geeks building "cool stuff in garages", but people who "make flappy bird" - you're not getting away from that $99.
- saagarjha 6y agoMany developers are paying for the ability to develop, not the development experience.
- Humdeee 6y agoI believe someone like Paul Hudson and the work he has done can influence a language's adoption by nearly an order of magnitude in the language's infant stages. I released a Swift 1.0 app back in 2015, and continue to provide irregular updates for it but still churns some decent income (to me). If not for him, I really don't think that spark of enjoyment would have happened. What he provided was two-fold: an enthusiast to Swift and the iOS environment, and also as a teacher and big source of documentation.
- gentleman11 6y agoUnreal engine is like that, except with fewer third party tutorials. It’s getting better but the c++ docs are almost as bad as having nothing. Some of them only have comments like “maybe refactor this” as a description, and the community wiki was taken down recently too
- ffhhj 6y agoYears ago I worked on the documentation for one of those big game engines. Previously as a "user" I suffered a lot with their physics system, and there was a big gap about its performance and best practices. After a long research in the source code and emails back and forth in the company I was able to fill those holes. My motivation came completely from within me, because absolutely no one in the company seemed interested on fixing the docs. It's the least important thing in most of these big companies.
- gentleman11 6y agoYour work is deeply appreciated
- SkyPuncher 6y agoI built a SwiftApp a few years ago. I absolutely loved working with Swift, but I could not stand the documentation. Apple was so happy to push breaking changes (without good documentation), that it made it very difficult to work with.
- rocho 6y ago> “Here’s the type signature, have fun!” My experience with Go libraries in a nutshell. One of the factors that made me abandon that language for others that for me are much more productive.
- EdwardDiego 6y agoYeah, I've found that quite often in apps/libs written for K8s in Go - wasn't sure if it was a Go cultural thing or a K8s cultural thing. If you're lucky you're getting an example or two in the README.md. The rest of the time, you're reading code to figure out the intricacies.
- rdn 6y agoAt least you can read the code, Apple's libs are closed source. You have to resort to reverse engineering techniques to fill in the documentation gaps.
- EdwardDiego 6y agoThat's a very good point. Reminds me of the bad old days of .NET (pre 2.0) where the documentation was a bit shit, and you ended up relying on Reflector to figure out wtf was going on.
- wlesieutre 6y agoAnd on a related note, I just put on yesterday's Under the Radar podcast episode, and their main topic is complaining about this same stuff. https://www.relay.fm/radar/204 https://www.relay.fm/radar/204 Makes me fell a little better knowing that professional iOS developers are having a similarly hard time with this, I was starting to feel dumb about it. I'm reading the docs, why can't I figure out how to use this?
- cvwright 6y agoAbsolutely. I’m a CS academic writing “real” code for the first time in 20 years. It’s really reassuring to hear that Marco Arment is also googling for the same SwiftUI tutorials that I keep falling back on.
- ben-schaaf 6y agoAt some point I had to read through some issues on the Firefox and Chrome issue trackers in relation to rendering on macOS. I kid you not more than once I read someone saying something along the lines of "No idea how this works, lets ask some Apple people at the next conference".