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/

Here's a TED talk on Thorium reactors. Why aren't you running them yet?

Just because it was shit 15 years ago doesn't mean it's still shit now.

http://web.archive.org/web/20060626083819/http://www.php.net...

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)

No, what kills me is

public Session getSession(Foo, Bar, Baz)

where Foo, Bar, and Baz are themselves interfaces, and I have no idea what implementing class I need, so I go searching, and after an hour of pain piece together that I need to instantiate a NotAtAllAFooButNeverthelessImplementsFoo, then pass that into the BuildingFactory class' static factory method to get an instance of Bar, and then I can just pass in a null for Baz, and it -seems- to work.

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")
        }
     }
  }

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.

an example for `PreviewProvider#previews` uses `.previewDevice("iPhone X")`, and i'm guessing that that string gets turned into a `PreviewDevice` via one of those `fromBlahLiteral` methods it implements? my guess is that `PreviewDevice` is some kind of opaque handle thingy (which is why it has no visible members/methods) but that... really should be documented

I think there's something to be said for javadoc, cargo doc, etc encouraging documentation to hew closely to the structure of the code as opposed to a free-form documentation system that can include multiple pages about tasks, getting started, etc. But the vast majority of projects don't bother to set that up, and the javadoc approach makes it very low friction to add docs to existing code that probably already has comments explaining how to use it.

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, no affiliation (also there Paul Hudson wrote the chapter about SwiftUI).

Get ready for documentation subscriptions. I wish I were joking.

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.

While the level of documentation that exists is usually pretty good, the sad fact is that most documentation doesn’t exist, and it’s entirely due to the fact that they are handled by developers/documentors separately. If you had developers documenting in-situ in the code, instead of WWDC slides, then it would be a lot better.

https://docs.microsoft.com/en-us/dotnet/api/system.string.su...

The MS docs from the late '90s through about 2015 were stellar. For example, look at the Windows Sockets docs[1], which came out of that era. Here you see information architects working at the height of their power: Content is broken up into conceptual ("About Winsock"), task-based ("Using Winsock"), and reference ("Winsock Reference") topics. They were doing this kind of structured documentation before DITA was a thing. It's a pain in the ass to produce content this way, but the results are wonderful.

Then came .NET Core: a fast-moving, community-driven effort, where the philosophy seems to be to get it working and then scribble down some docs later. The result tends to be a huge wall of text with conceptual and sample topics jammed together ([2]), and you're lucky if the API reference gives you anything beyond parameter names.

Azure docs suffer from a different problem. It seems they've tried to apply some kind of rough information architecture, but the quality isn't great. I've looked at the GitHub history of some of the shoddier topics, and they're often written by junior Product Managers who are fresh out of college. I encounter a lot of imprecise, colloquial English describing out-of-date screenshots.

I don't mean to belittle the people who work on .NET Core and Azure. There's a ton of content that needs to be written for these products, and it's a thankless task for the devs & PMs who do the heavy lifting now. I'd really like to see some dedicated technical writers come in and bring the quality back up to their old standards.

[1] https://docs.microsoft.com/en-us/windows/win32/winsock/windo... [2] https://docs.microsoft.com/en-us/aspnet/core/fundamentals/ro...

Back in the day, when Sun was still in-charge of Java, I had my 1-person consulting company partner with Sun and become an official "Certified Java" organization... Great, I thought - now I can get some better documentation...

Sure, Sun replied - but first you have to buy a $30,000 server... Thankfully, .NET hit public beta about then and I have never looked back.

It got so bad that a VP ended up making a pronouncement, declaring a war on broken links. He announced a multi-year plan to reduce and eventually fix all the broken links on MSDN. This was the vacuum that was partially responsible for the birth of Stack Overflow.

Probably Scott Guthrie initiated that. As some nobody I once emailed him directly because I'd discovered a bug in some framework thing with a reproducible example. He actually replied and cc'd in the relevant people at MS and after a short while there was a workaround and a fix and a KB article or something (it's so long ago I barely remember). Impressed? absolutely. MS still have some pretty good and accessible folks, and I'm a huge fan of Scott Hanselman who's a great brand ambassador for DevDiv (and not beyond a few self-deprecating MS jokes about the company's past).

Documentation pages that showed a method's signature with no explanation of the function or example usage. So many times I'd look something up only to find the method name parroted as a full sentence; and those method names were often obscure to the point of meaninglessness.

Anything that was available online, official or not, was inferior to that. I'm not sure if it was deliberate, but it significantly hampered the utility of pirated copies of Visual Studio - since MSDN docs would require a lot more CDs than the software, most warez releases stripped them out. And in the developing world, where such pirated software is readily available on physical CDs sold by street vendors, they would usually be priced per CD regardless of what's on it - so a complete VS+MSDN bundle would be a lot more expensive, and thus in relatively low demand, and not widely sold.

It's a hard sell to tell an IT decision-maker in a different team/group that you need to configure things "just so" (think TechNet versus MSDN for configuration/operational articles) when all you have to point them too is a non-official blog post...

(Don't even get me started about the quality/out-of-date materials for things like Dynamics 365...)

In the personal computing world, first parties can't build enough user software.

Furthermore, software availability and reliability lag third party developer and development ecosystem health. A bad experience doesn't hurt the platform today, it hurts the platform in 1+ years.

And perhaps even worse, steps to address it take effect over a 1+ year timeframe as well.

Apple's been able to leverage iOS market share into papering over the desktop reality, but they're going to find the emperor has no clothes real quickly if anything about that calculus shifts in a bad way.

It didn't work out for them back then, and so we got native apps and the store. But I can't help but think that Apple still sees it as a sort of compromise of their ideal vision of what the platform should really be like, and thus dev ecosystem evolution is mostly on the backburner. Just look at how long it took for Swift to appear, despite Obj-C being really dated by that time.

It's the "culture that rewards and values the work" that's really the issue, I suspect. Apple certainly used to have a culture of good documentation, and I know they've hired good writers, technical and otherwise, over the years. It's actually kind of difficult to explain why their docs are the way they are, other than just not putting any real priority on the necessary work.

I thought that was what the $99/year was for.

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.

MSDN Library. Everything old is new again.

The documentation of software packages, APIs, and driver kits was freely available online.

No, it hasn't. It was originally available exclusively to subscribers, and only on CD. MSDN started before the web existed.

Eventually, the documentation became free on the web.

No it wasn't - the subscription service shipped CDs (and later DVDs) with technical articles, updated SDKs and the like. The actual documentation was always included with every Visual Studio version on the installation discs.

I remember quite vividly the "joy" of re-installing the latest version because the documentation format was incompatible between releases and you could either reinstall the new version from disc (which took ages) or convert the already installed one (which also took ages, but not quite as long as juggling 4 CDs - it had to "rebuild the index" or some nonsense like that IIRC).

So if you owned a physical copy of any Visual Studio edition, you also had the documentation and thus no need to subscribe to MSDN (apart from the technical columns, SDK updates and the magazine, which any reasonable boss would allow you to read during work hours).

You seem to be arguing against a negative value judgement which I did not make, or even suggest.

Here's a pretty damn cool app: https://swiftui-lab.com

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

Even displaying rich text (non editable) is a wee bit tricky and severely under documented.

Apple: Fuck off Developers!

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.

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.

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.

For example, Previews are one of SwiftUI’s major features. Here’s its docs page: 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-...

Could you construct that example from having read the documentation? I doubt it.

Apple was so happy to push breaking changes (without good documentation), that it made it very difficult to work with.

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.

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.

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?

While I'm not an iOS dev I have seen a trend where people have stopped putting in dates of their coding tutorials.

https://developer.apple.com/documentation/swiftui/progressvi...