if developer_docs == bad then app_quality = bad; Coders slam Apple for subpar API manuals

Apple developers are becoming increasingly vocal about their displeasure with the state of the iGiant's programmer documentation, which they depend upon to craft iOS and macOS software. In a blog post on Monday, macOS developer Michael Tsai makes note of a handful of fellow coders expressing discontent with Apple's …

[karlkarl]

The C and Objective-C docs are generally pretty decent. The manpages are generally very up to date.

As for the kiddie stuff like Javascript and Swift... well, I partly blame the design of these languages (and the developers for choosing them).

Prediction: Swift will be gone in 5 years and Apple will claim to never have left C (or Obj-C).

[BillG]

You're Only As Good As Your Docs

Documentation is the forgotten value proposition. It's like technical support, management thinks it's magic and "just happens".

Good, clear documentation is a powerful sales tool. Potential customers download docs and read a few pages from the browser cache. If it's good enough they download it to the hard drive for later use. If it sucks, they leave the website, never to return.

I've seen companies beat out superior technology competitors because their docs were better. I've also seen designs wins reversed because the docs sucked.

[Anonymous Coward]

A decent into entrophy over the last 35 years..

The first edition of Inside Mac starting in 1984 is still the best platform documentation I have read. Anywhere.

The second edition of Inside Mac was less concise and more confused but pretty much kept Caroline Roses original focus on what we needed to know to ship software.

After the Nexties took over in 1997 during the next decade the MacOS documentation degenerated into little more than a collection of random man pages. Essentially useless. Third party books were the only way to gain any useful knowledge about how to develop non trivial software for the platform. Which was a bit of a surprise as although the NextStep 1.0 docs were dreadful by NextStep 3.0 the programming documentation was almost usable.

And for the last 15 years all usable MacOS/iOS documentation when found must downloaded immediately and kept as it will disappear from Apples website or else rewritten into some utterly useless revision.

So how about someone at Apple goes and reads the original Inside Mac to learn how you actually write useful platform API documentation. Hint, its not a huge collection of completely uninformative and useless man pages. Which is all they offer at the moment.

[Ian Joyner]

Re: A decent into entrophy over the last 35 years..

I don't know why you post as Anonymous Coward (maybe an Apple employee or developer) – this is one of the best Register comments I've ever read!

Unix has a lot to answer for with its man pages. At the time it seemed like good documentation because you could just type 'man <whatever>' on your terminal and not have to open up a paper book.

But really it is tedious and boring documentation. Unix commands tend to be overly complex trying to address all possibilities (which is rather against the spirit of what unix software development should be – small single-purpose programs chained together).

The old phone books and old original 5 volumes of Inside Mac were great.

However, at the time, the example programs that programmers used as a base were really badly written and messy.

[JLV]

FWIW Erica Sadun was the author of a fairly complex and in depth iOS book. Not always the easiest to grok, but she clearly knew her way around much better than Joe “Hello World” Author, esp when it came to deep API subtleties.

So if she’s struggling, a certain very lucrative corporation is failing. Not that another, even more market-capped corporation, doesn’t also have many atrociously outdated user docs, but I digress.

Oh and don’t get me started on the utter shite doc wrt ‘mdfind’ which is the bash API to Spotlight. In theory it can do much the same as ‘find’, like finding all files changed in last 10 minutes. In practice? Utterly abstruse parameter names and no doc whatsoever.

* past tense because I read it years ago, in Objective C times.

[Andrew Hodgkinson]

It's just part of modern software engineering; with each passing year, code gets more bloated, less reliable and more poorly documented. Upcoming engineers either just can't be arsed documenting anything or literally don't know any better and are somehow unable to figure out for themselves how vital good documentation is. Rigour is dead; RIP.

As with most recent Apple problems, the most serious rot seemed to start quite suddenly, around the iOS 7 / OS X 10.7 era.

[Dan 55]

Upcoming engineers either just can't be arsed documenting anything or literally don't know any better and are somehow unable to figure out for themselves how vital good documentation is. Rigour is dead; RIP.

Training happens by osmosis, code review is dead, and it's all about closing one Jira ticket after another even if the next one undoes the changes made by the first one.

As with most recent Apple problems, the most serious rot seemed to start quite suddenly, around the iOS 7 / OS X 10.7 era.

I think it went downhill when Bertrand Serlet and Scott Forstall left which was around that time.

[Duncan Macdonald]

Cost and shortsightedness are the reasons

Writing good technical documentation requires good (read expensive) people. Doing the documentation for IOS to the standard that IBM did for OS/360 would cost several million dollars. As this cost does not have an immediate payback, the big bosses at Apple do not think it worthwhile. They do not realize that without good technical documentation, their products are certain to deteriorate in quality until eventually they lose the flagship appeal that currently allows them to grossly overcharge its customers.

Apple bosses need to realize that technical documentation needs to be done well and by professionals - not by the cheapest outfit that they can find in India.

Icon for what will happen to product quality without good documentation ===>

[Steve Davies 3]

Re: Cost and shortsightedness are the reasons

A very good post especially if you read the article about the salvage of the IBM 360 where they found a complete set of schematics for the beast. Those were the days. When the documentation shelf weighed more than the computer that came in 19in racks. Or when pretty well every printer in a country was use to print OS manuals prior to a major release (Dec VMS V5.0)

Writing good documentation is not easy or quick. It also requires dedication. Much like writing proper tet plans. All a dying art IMHO.

Those were the days eh?

[Warm Braw]

Re: Cost and shortsightedness are the reasons

The documentation for VMS was sometimes more complete than the software: I remember at least one layered product that lacked certain documented features on first release because the technical writers, who were important components of the development team, had read the spec more diligently than the software engineers!

Documentation now is almost universally abysmal - automatically generated listings of API signatures with a few annotations culled from comments in the source code is not documentation, particularly when you have access to the source code anyway.

There's been a persistent undercurrent of mysticism in IT - keeping close those darkly-guarded secrets that preserve the anointed status of the holder. If you want people to use your software you have to make it capable of being used. If you don't want it to be used, why write it in the first place?

[usariocalve]

It's pretty ridiculous. For example, there is little to no documentation on HealthKit. Did you know that you need to store your query anchor? Are times in UTC or local time? The documentation is silent. Devs just use stackoverflow, which is basically lore from people that got things to work.

[ThomH]

No part of the API uses local time, so you can make a pretty confident guess on that — it's always timestamps relative to the epoch that can be converted into a time relative to a specific timezone if you request.

This I can say because the developer documentation used to be great — five or ten years ago all the information was present for each class on a single page that search engines could easily index and a quick command+f could quickly reverse. The last couple of times I've tried to search it's been a miasma of incomplete snippets of information served dynamically that seem impervious to attempts to bookmark.

It's almost exactly as if Apple just got the memo on Web 2.0, fifteen years late.

[Dan 55]

No part of the API uses local time, so you can make a pretty confident guess on that

You shouldn't even have to guess, it should be there in black and white.

[Richard 12]

Even simple things are missing

Application packaging and installation is almost totally undocumented. There are merely a few scattered single-topic blog-style posts.

If you don't use the xcode built-in wizard, you're on your own with effectively no documentation from Apple whatsoever.

That'd be ok if it weren't for the fact that the xcode system, like most of xcode, only seems to work if your app is trivial (one executable, no frameworks or dylibs) and you're not using automated build systems. Jobs forbid you use CI, that's right out.

The Apple framework/dylib system is also batshit insane, which really doesn't help.

I assume that nobody within Apple actually uses any of these things.

[Anonymous Coward]

Almost all documentation is terrible

Documentation is an afterthought, there is the perception that the code has to get to the customer first to realise revenue and the docs can come some time later. Docs written by a Tech Author often without experience in the problem domain, working from poorly elaborated specs (or "stories" if you like being fashionable) and trying to pump information from overworked Devs who are stressing about the next sprint and the need to present progress at the next stand-up unless they get a black mark.

So the docs are late, inaccurate, poorly written and untested. No one gives a shit because the next release is coming and there's the ££££.

Then the customer satisfaction surveys come in and managers wonder why the perception of quality is so low. Clearly the software is buggy, so the Devs and and QA get whipped harder to work longer hours and make less mistakes. But that's not the problem, and it's not the Tech Author's fault either. The docs are just as, if not more so, important than the code.

Nothing, nothing should be considered released until the docs have been proof-read by multiple people and tested. Yes, tested. It's perfectly feasible to test docs. Only once that is done and the docs pass should one push a feature on to Release.

End result? Happier customers who understand what the software/service does, how it works, how to workaround issues, how to self-help, fewer Support calls, less stressed out Support Techs who can't understand the shitty docs and have to call on Devs who can barely remember what they did in that version before is was over three months ago.

[Colin Wilson 2]

Part of the problem is that almost all of Apple's API/SDK help these days is auto-generated from Markup in comments in the source code. What Apple refer to as 'Quick Help'

So the whole system is entirely dependant on how clearly and accurately the (Apple) developer comments their code. There are obvious pitfalls to this(!). Programmers usually aren't technical authors. And often the code gets updated - or new methods get added without the comments being updated - so the whole thing gets less and less reliable.

Xcode provides basic templates for this that you can use - if you know about them. But many people don't as Xcode itself isn't very well documented.

[Josco]

"But many people don't as Xcode itself isn't very well documented."

I agree with that. I am not a developer or code writer in any shape or form, just an inquisitive amateur, but I've had an idea for a (brilliant) iPhone app that I fancied having a go at. The help for the Xcode SDK is no help to me and I've got bogged down at the first hurdle....

Ah well, back to HTML, CSS and a little poorly written PHP. My plans for a money making app on the back burner.

[Ian Joyner]

= is equal not assignment or implies

Why is the natural world being corrupted by the constraints of bad programming languages. '=' means equals, no need for a second one. = does not mean assignment, that is storage a value into a memory location. Also programmers have a bad habit of putting spaces inside of parentheses ( like this ), or worse( like this )which looks ugly and goes against the typographic design of parentheses. The horror of CamelCase is also appearing moreAndMore, instead of white space as a separator, or nicely-hyphenated words. Programmers have a bad habit of choosing the worst way to do things.

We should get back to the original elegant notations of logic in philosophy and mathematics (abbrev maths, with an 's').

Everyone should resist this move to NewSpeak.

[Ian Joyner]

This is a serious problem

I could say that Apple moves too fast, continually changing APIs, Xcode, and language (Objective-C to Swift). This means experienced developers (like me) give up at some stage. I did an Eiffel compiler on Mac. Originally done for OS 9 on CodeWarrior. Then OS X came along (really a better fit) but CodeWarrior was dropped for Xcode. That was fine, but Xcode kept changing in huge ways every release. It was not really possible to sufficiently integrate another language with Xcode.

But it is not Apple, but technology that moves too fast. So us oldies can't keep up. And now teaching students I feel it is a losing race to even get them to the starting blocks.

I actually lobbied Apple to look at Eiffel – a much better language than Objective-C and way better than C++. I did an apps in Objective-C for iOS, and would like to do in Swift sometime, but with other workload (now teaching) have little time for writing software.

As many (such as the highly respected Scott Anguish) have pointed out, the documentation keeps changing – and for the worse. I could not keep up with all the rereading. WWDC is a great way to find out what is going on, but it fills really quickly mostly by those who want a boondoggle. There are also too many videos to keep up. My last company begrudgingly sent me (that employer did not last much longer). Then iOS came along, alas having supported Apple through bad times, their success was too late for me. I suspect this is the case with many experienced developers who really have found other avenues now.

[The Indomitable Gall]

Re: This is a serious problem

I haven't really been able to examine Eiffel closely, because as soon as I look at it, I see yet another impenetrable jumble of fixed-width letters.

Why are we so obsessed with fixed width? It is hard to read, making it easy to make mistakes.

Why are we so obsessed with plaintext? It's so inconvenient that we spend our lives hacking IDEs to try to present layers of visual meaning on top of the text through colouring and font weight. And still it lets us type illegal code -- syntax errors.

Creating a truly smart language integrated with the IDE would be simpler than hacking the editor to highlight errors.

Just look at the STRIDE language, invented as a teaching language. Almost all the flexibility of Java with practically no scope for syntax errors.

[Ian Joyner]

Re: This is a serious problem

Actually Eiffel was designed to be nice with proportional fonts, not fixed width. I do agree we should move away from text and make text subservient to the semantics and structures of programs which can be presented visually, or in any syntax we like. Eiffel would be ideal for such an effort since it has clean and clear semantics.

Is this the kind of thing you have in mind? -

http://ianjoyner.name/CompEditor.html

Thanks, I'll look at Stride.

[Ian Joyner]

Re: This is a serious problem

I think the frame-based editing looks promising. Editing should be more semantic. I had a discussion with a colleague last week who was saying how great vi and emacs were because you could easily type a very powerful command to change 1,000s of things in one hit. However, if I want to change the name of a variable xyz, I change all the strings all the strings xyz, whether they are actually that variable or not. Editors should be more semantic and graphical. IDEs leave lots to be desired.

I looked at Stride (what meagre stuff I could find). It looks like it might be based on the Blue teaching language developed at Sydney University. However, I am unimpressed by the C/Java-like syntax complete with inane (). Ugh, talk about text!

[Ian Joyner]

Paper (or online) documentation – how quaint!

As I said in last comment, I worked on Eiffel on MacOS (9 and X, having previously completely written an Eiffel compiler on Burroughs/Unisys MCP systems). One of the advantages of Eiffel is you define whole class in one place. The compiler can automatically generate the short form which documents the API, complete with checkable assumptions (assertions) as Design by Contract. No need for separate .h interface files as in archaic C-based languages. This provides THE definitive API for all software. Separate documentation always lags behind and as Scott points out varies in quality.

It is a shame that we have not been able to persuade Apple to use Eiffel instead of developing its own Swift language (which mostly leaves me cold, although generally an improvement of Objective-C). Microsoft also went away and did C#, although Bill Gates adopted the phrase "Trusted Computing" from Eiffel's designer Bertrand Meyer. Now the others are all doing their own proprietary languages and most of them are nowhere as good as Eiffel.

This also means we have further silos of software development between Apple, Google, and Microsoft.

The main point of this comment is to say that API documentation should be directly generated from the software. That leaves documentation writers to concentrate on explaining the concepts behind the software. Developers need both – absolutely accurate and up-to-date APIs and conceptual documentation.

[AndyDent]

Apple don't know what's been archived

It's telling about the disorganised state of the docs team that when you start with Apple's own *current* StoreKit docs (https://developer.apple.com/documentation/storekit) you are directed to https://developer.apple.com/documentation/storekit as Related Documentation: Receipt Validation Programming Guide.

I've been developing in the Apple world for around 30 years. I still have paper copies of Inside Macintosh to taunt me what quality docs look like (plus I do ports of old Mac code to modern Mac or Windows OS and the last time I did one, I couldn't rely even on the archives!)

With all the cash Apple have sitting around, I am utterly bamboozled as to why they don't see this as a problem needing fixing.

it's NOT a Swift vs Objective-C thing, it's an arrogant neglect syndrome.