Apple’s terrible documentation

In the last year or two, I’ve come to realize that the main obstacle to doing my job is documentation. Or, more specifically, the blatant lack of documentation provided by Apple for its platforms.

Apple provides developers with a set of tools – APIallowing us to create apps for iOS, iPadOS, macOS and tvOS. In many cases, figuring out how to use these APIs is straightforward. Just as a screwdriver can be used in very few ways, in many cases there is only one obvious way to use the API.

However, while users rightly demand more and more complex and sophisticated applications, APIs often have to become more and more sophisticated and complex too. It suddenly turns out that in addition to simple screwdrivers and hammers, you already have power tools and complex saws, and everything turns out to be much more troublesome than it was before.

When you buy real tools, you expect to receive a user manual with them that describes how to use the tool you just bought. To some extent, there is a rough analogy for APIs – most platform owners provide documentation. Basically, this is the “user guide” of the API.

Apple’s documentation has been pretty poor for years. Over the past couple of years, she has gone through the stages of “bad → terrible → disgusting → shameful”. Too often, when learning how to do something new and use an API I’m not familiar with, I’m stumped by these three daunting words:

No overview available

So Apple says, “Fuck you, figure it out yourself.”

The situation with No overview available so bad that popular resource on Apple (which by itself, probably, would not be needed in an ideal situation), used this phrase as a name siteemphasizing how bad Apple’s documentation is.

Moving progress forward does not improve the situation. how pointed me on twitter my friend Adam Swinden, after the deprecation of some APIs, sometimes they don’t even think about adding documentation to new ones. Estimate the difference between this API and who came to replace him

“No overview available”. Fuck you, figure it out yourself.

A couple of years ago there were two stunning API related UICollectionView:

Not less than a year, maybe two, the best documentation on these new and important functions was hidden in header files… It’s disgusting.

IN recent podcast site Under the radar my buddies Marko and Dave continued the theme of Marko’s transition to Swift and SwiftUI. In this episode, Marco and Dave have eloquently described the horrific torture that Apple developers endure as they try to figure out how to use Apple-provided tools. There is a transcription of the podcast at the end of the post, slightly edited for readability.

I beat this drum for several years. I had no idea what the problem was on Apple’s side.

  • Doesn’t the documentation department get time to react to new APIs? (I would have believed it.)
  • Is documentation not considered a requirement for API release? (I would definitely believed it.)
  • Is the documentation department doing a poor job? (I doubt it.)
  • Is the documentation department too small? (Probably.)
  • Is the documentation department hindered by politics and conflicts? (Probably.)

Whatever the problem is, it needs to be addressed. The problem has been aggravated for several years now, and the cup of patience has finally run out.

Under the Radar podcast transcript

Marco: If you learn SwiftUI, then first of all you find out that the existing teaching resources are pretty terrible, because it is a very young language / framework / and just a way of perceiving things. It is so young and changes so often (like Swift in its youth) that many tutorials, code examples, and answers on Stack Overflow have simply ceased to be correct. Simply because everything has changed from the previous year. Or because the answer was in beta, and in a later beta released in the same year, the name of the class or the way it performed a function changed.

There is now a great need for documentation support from Apple. One of the great things about PHP is that it always had excellent the documentation on your website.

On php.net any function can be found and hotkeys have been added in the editors, so for example in Textmate I can press ⌃H and a window with documentation will appear from the website php.net about the function my cursor is currently on. This language has always had great documentation. On the documentation pages for each function of the language, and there are many of them, there were snippets of code examples. And there are comments! Therefore, even if the example code does not quite suit you or does not answer your question, comments usually do it.

This is what I would like from Apple’s documentation – these little use cases, because they really help explain how something is done or what a function is for.

When we started moving into the territory of SwiftUI and Combine, and all these high-level concepts, it all gradually gets more complicated – the same will be true when Swift implements async/await, presumably in a year or two. Many of these concepts become more difficult to understand because they are very abstract and have very simple names that make it difficult to tell what they do and how to use them. So we all have to go to StackOverflow and blogs with tutorials, because their own documentation (even if there is one, this is already a big event) is so laconic and minimalistic, as if it was designed by John Ive [известный дизайнер-минималист]…

Dave:… It’s like a big white room…

Mark: Yes, it’s a big white blank page. It says “this type is needed for this particular thing,” after which there is no context; there are no examples showing when to use it, how to use it, whether to call it in a specific way, like a constructor.

These small snippets of code on the doc pages could be of immense value, as is the case with PHP. For example, “here’s a four line example of how to use this thing.” And when I study all this, I miss it so much.

I can imagine that beginners perceive almost all programming elements this way; Since I’m just as new to Swift and SwiftUI and all the concepts that SwiftUI is built on, I feel for the first time in a long time what it’s like to be a beginner. I would really benefit from better documentation, I would benefit from someone (probably Apple) putting a lot of effort into not only writing the documentation, but also updating it as the language changes.

This problem occurs when young languages ​​or frameworks are actively developing. If you are learning from the blog posts and answers on StackOverflow, then they all get out of date pretty quickly, as I said earlier. No one at Apple is full-time to ensure that all of these blog tutorials are updated when the language changes, so most of the time they are not updated. Or some are updating, some are not, so it is difficult to understand what you are facing.

But even in such a situation, when SwiftUI has attracted such attention of fans of the language over the past year, there is still very little material on it. There is even less material on anything deeper than trivial use cases. For example, if you need to make a technical demo in SwiftUI, in which there should be a button with changing state or number increments, then great! There are a million posts about this.

But sooner or later you have a question: “Okay, how do you tie this to the rest of the application?” This is a real application that has real needs for persistent data storage, different screens and the like. Once you add complexity to real-world applications, most of these tutorials don’t cover it. Dave, I once had to adapt SwiftUI from these trivial tutorials and Apple’s WWDC talks to answer the questions “How do I connect this to my database?”, “How do I connect this to my file download system or sync engine?” And there were many such questions. I think I figured it out in the end, but heck, this is all non-trivial and not obvious, and there are a lot of weird little subtleties.

Dave: I completely share your pain. It frustrates me so much that there are only a couple of really great SwiftUI resources online. For me it Hacking with Swift Paul Hudson… About 80% of my knowledge about SwiftUI comes from his website and his videos. He organized an excellent learning process: videos that show one level deeper than a trivial example, after which your knowledge becomes trivial “plus a little”. This is an incomplete example, it still has a lot of rough edges that you mentioned. I am sure that I will continue to face such problems: you want to do something a little more than the most obvious, but suddenly it turns out that you are falling off a cliff, and all that remains is to wish yourself luck.

I remember meeting a couple of people teaching in the Apple community in early spring. These are the people who speak a lot at conferences, hold workshops, and so on. They said, “You know what? It looks like we won’t be able to go to conferences for the whole of 2020, we won’t be able to do much. Hey Apple, we have tons of very talented teachers in our community with tons of free time. It would be great if you took advantage of this. “

Sadly, it’s almost the end of the year, and the company doesn’t seem to take advantage of it. It doesn’t seem like she took any steps in this direction to use all these people, who are great at explaining material and creating example applications, to do this work that could help people in your environment and mine. I truly sympathize with those who come to SwiftUI without decades of programming experience. If this is the first app you learn, then in some ways it is pretty light. A very primitive SwiftUI app is actually easier to build, probably easier than most primitive UIKit apps. But as soon as you start doing something more, it instantly becomes very difficult.

I also think that people who build the platform are best suited for creating documentation, but in the case of documentation, this is difficult. They can work on the documentation so that it is available as the technology is released. I sympathize with everyone who educates Apple Platform Developers – when a new SDK is released or a new beta is released, they have to stay awake for three days, hectic trying to update all their content and uncover new features. They do a great job, and I appreciate it, but it shouldn’t be a fuss.

Could have made Apple’s documentation department work on it in concert with people writing APIs for months. Therefore, right on the day they were released, the documentation would have a wonderful set of code examples demonstrating how to use the API.

You are absolutely right, especially regarding SwiftUI – the problem is the lack of traditional documentation … If you go to the documentation for Text in SwiftUI, then the type View there are many different modifiers that can be applied to this View… They seem to number in the hundreds, if not more. However, having a huge list of everything that can be done with Text, does not help. We want to know the following: “How do I make the text look like this?”, “What if I need multi-line text?”, “What if I want multi-line text to consist of a certain number of lines, and then align in the middle?” In doing things like this, we need examples. I don’t think that the general list of cases that people use in reality is particularly wide. I understand your pain.


Advertising

Embody any ideas and projects with the help of our VDS with instant activation on Linux or Windows… The server is ready to work in a minute after payment!

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *