Apple Developer Documentation’s Simple, Fundamental Design Flaw
Not every hierarchy is a navigation hierarchy
For anyone developing for Apple’s platforms, Apple Developer Documentation is a essential resource. On the web at https://developer.apple.com, it’s one of the few places to get detailed authoritative information about Apple platforms.
Unfortunately, information on most Apple Developer pages is harder to understand than it needs to be because of a simple misconception apparent in the design of the pages.
(Full disclosure: I applied to work on the Apple Developer Documentation team in 2017, had a positive experience, and was invited to reapply later or apply to another team, but did not because I did not want to relocate.)
An example illustrates this clearly. Landing on this page on iPhone:
Identifier for what? What session?
When there is more screen space, as on iPad, the results are a little better:
By looking in the navigation bar, and noticing the third of four items that is the immediate parent of this page, we can see that we are in fact looking at an instance property of ARSession, the fundamental starting point of Apple platform AR experiences.
Saying “identifier is an instance property” is incomplete, equivalent to saying “identifier is an instance property on”. Instance property on what? It’s an incomplete statement.
This is the flaw: Each page is designed as if it completely independent, and the parent is of no relevance other than as the source of the navigation.
If there is any doubt, inspecting the element on desktop confirms that the navigation bar that embeds ARSession has the aria accessibility tag “Breadcrumbs”:
The misconception is not the fault of ‘the designers’. The documentation is organized in a single unified hierarchy; the pages have designed with best practices for a website organized in a hierarchy. And the unified hierarchical organization of developer.apple.com is good, actually: good for navigation and good for general organization of a massive complex topic.
This is why the page becomes even less intelligible on iPhone: Breadcrumbs are the first thing to be sacrificed, as it’s a safe assumption this not important information. On pages that describe aspects of objects in object-oriented programming, this is a fundamental mistake.
To look closer and at possible low-impact solutions, it’s necessary to look at the what this concepts being presented actually are.
Object-Oriented Programming: State and Behavior
Object-oriented programming remains fundimental to development for Apple platforms and everywhere and not just for legacy reasons. One key reason is that object-oriented programming helps make programs easier to reason about — managing complexity being a fundamental skill of software development.
What is an “object” in object-oriented programming? One definition perfect for us is an object encapsulates state and behavior.
“State and Behavior” maps to the categorizations of identifier above: state is encapsulated in Instance Properties and Class Properties, and behavior is encapsulated in Instance Methods and Class Methods.
What is “encapsulated”? It means, among other things, that these properties and methods are defined in terms of the class, or object. They have no “global” meaning. They only have meaning as part of the object they are in.
Another analogy would be transitive verbs in English grammar. A transitive verb requires a direct object to be grammatically correct. Conversely, an intensive verb does not and can stand alone: I am going to shop [period], with shop being intransitive. A transitive verb requires a direct object to receive the meaning: I am going to buy [period] is grammatically incorrect if there is no direct object in the sentence specifying what the speaker is going to buy.
Instance Methods and Instance Properties, and Class Methods and Class Properties, make no programmatic sense outside of the type — why the page for ARSession.identifier is unintelligible.
Solution: Seeing in Context
On iPhone or other compact size classes, as seen in the first image above, currently the type is not even visible without tapping the dropdown “Documentation.” A simple stopgap solution is evident. Pages in the instance/class object-oriented categories could show the parent of the current page. While a deviation from general principles of navigation, the immediate benefits of seeing the type that the page is in fact about will make these pages dramatically easier to understand.
In the long term, documentation teams need to work with designers to find a way to identify how to present all of the necessary context on each page for each symbol. If the symbol is a instance method or class method or instance property or class, it’s essential for the type to be displayed prominently.
There are more possibilities for embedding domain knowledge into the navigation and presentation. For example, the Vision framework uses a multi-level series of subclasses on the base VNRequest and VNObservation to specialize vision capabilities, an appropriate design choice for functionality that is is specialized additively: Subclasses add new functionality but retain superclass’s methods and properties, which remain essential.
Currently, though, to try to understand a Vision subclass requires keeping multiple pages open and manually reconciling them, as well as reading superclasses while trying to keep track of . Embedding superclass methods in the child page, either with specialized notes or just as a reduncdency, would make Vision Request and Observation specialized task pages more complete and easier to understand.
Regardless, developer.apple.com needs to ensure. The site is essential, and is generally fast, complete and good looking. Web sites remain the best way of presenting these vast libraries of information. With the slightest tweaks, surely the result of misconceptions rather than intentional, the ability of Apple to communicate to platform developers will be even more effective.
Mike Sanderson is an iOS developer in Brooklyn, NY.
