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.
I 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.
I 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?
I 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.
Global 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.
For 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.
I 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.
IMHO 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.
The 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).
That's certainly true for the standard library and the documentation on the language itself. However for the internals, this wasn't always the case and it looked more like this:
On 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.
Same; 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)
I 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.
There'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.
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.
Yeah, 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.
For 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.
I 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, no affiliation (also there Paul Hudson wrote the chapter about SwiftUI).
> 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.
That 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.
A 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.
For all the crap that Apple, Java and other open-source people have piled on Microsoft over the years, their developer documentation has always been very good. Yes, there are rough-edges.
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's mocked, but the underlying observation is astute.
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.
If you recall, back when the first iPhone came out, the idea was that Apple itself would be the only provider of first-class software for it, and everything else was relegated to web apps.
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.
I wouldn't say it's always been very good. How well do you remember MSDN? In the mid-2000s, Microsoft documentation lived on three or four separate sites, and I don't remember the names of all of them. The two that spring immediately to mind are MSDN and TechNet. MSDN had the infuriating issue of broken links. You'd be deep-diving on an issue, find a link to an article that looked like it might perfectly address your question, and... 404.
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.
> It got so bad that a VP ended up making a pronouncement, declaring a war on broken links.
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).
They also suffered the same problem mentioned in this post.
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.
Heh... well, I am old enough to remember the offline MSDN - which was great, and the rough transition to online - which got better, eventually... (and the rise of StackOverflow makes more sense in that context) but then at the beginning of the "cloud-era", IMO, it got worse again - to the point that I was constantly complaining about blog articles by MSFT employee's that really should have been folded into the actual documentation/KB instead...
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 late-90s to mid-00, if you did any serious Win32 or .NET development, you had the MSDN Library installed locally - it had its own help browser, with integrated search and index. The latter was especially useful, since it contained all structs, classes, interfaces, functions etc, across all platforms for which docs were installed.
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.
For Microsoft it depends on when the docs were written.
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.
I use C# daily and most of the time the doc is fine. I agree that sometimes dotnet core docs are a bit messy and frustrating, but still quite good and useful.
It's not really the size of the company. Anyone qualified to write good documentation can make better money, work on more interesting things, and advance their career by actually working on the code. Without a culture that rewards and values the work it doesn't get done.
Well, not everyone who is qualified to write good documentation wants to work on the code, nor would they necessarily be as good at writing code as they are at writing documentation. If you're writing API documentation, you need to be enough of a coder to understand what the engineers are talking about -- and what they aren't talking about but really should be! -- but that doesn't mean you need to be coding at a level where you could have a career writing apps built on that API, let alone coding at a level where you could have a career implementing the API itself.
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 don't think this truism actually holds weight. Some engineers don't want to write documentation, sure. Maybe even most don't - but some actually do enjoy the process of writing good documentation, and they find satisfaction in creating knowledge artifacts that make their code easy to understand and use. It's not enough to just find these engineers, however - they need organizational support so that they have the right tools to create and share good documentation, and are appropriately encouraged to do so.
Reminds me -- it used to be that I could plug my Macbook air into a monitor and arrange my windows, and it would return them to that position whenever I'd disconnect and come back. That feature vanished as of ~2018 and you have to buy some app to get it back.
My Macbook pro still does this. Granted, it's a little wonky. If you alter the window in any way while disconnected then it might not return to the original location. It also doesn't preserve any new desktop environments created on the external display.
They actually have a department to write the documentation. The problem is that it’s a separate department from the people who design the libraries themselves, which means instead of having high quality documentation throughout, you only get the documentation that the doc team had time to write. It’s why most of the APIs are minimal at best in terms of documents.
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.
That's a bogus claim! The MSDN documentation has always been freely available. The subscription service included all of Microsoft's software editions for development purposes and that's what subscribers actually paid for.
The documentation of software packages, APIs, and driver kits was freely available online.
That's a bit unfair. The web is what made it easy to publish at no cost, CD's still had mail and print costs associated so it made sense to send documentation with the software packages it... documented.
> It was originally available exclusively to subscribers
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).
I'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.
We 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.
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.
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
Good find! For some reason buried two levels deep from the Previews page. I believe you're right that it's silently building a PreviewDevice from the string. You can make the PreviewDevice explicit (as shown in the Hacking with Swift code sample), but nice tidbit that you don't have to.
That I could probably look at the source and figure things out.
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.
rustdoc has the ability to embed usage examples in the doc comments, and automatically test them. also module-level documentation is doable via doc comments in the module main file. rust doesn't force you to write good documentation, but the tools are all there and I often see great documentation for rust crates that was generated with cargo doc. For example the Rocket docs are full of code examples on both the module and function level: https://api.rocket.rs
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.
That’s the barebones minimum, because in those contexts the examples are going to be relatively trivial. Often I find them to be no more helpful than the signature doc itself.
Even trivial examples that actually compile are better than none. because rust uses real code and markdown reading code and docs is the same thing in many cases, no need to even render to html, absolutely minimal markup noise.
I love rust docs. Speaking from many years of using mostly poorly maintained javadocs and well maintained man pages.
Yes 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.
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.
stupid 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.
I 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.
Apple figures developers will still pay them $99/year even if they provide them with poor documentation, and unfortunately, it looks like they're right.
Apple: 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.
I 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.
Unreal 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
Years 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.
At 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.
That'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.
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?
Absolutely. 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.
At 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".
I worked at a phone company that was collapsing in market share and one of the things that always stuck out to me was: complex signing process + documentation.
It seems that as you get larger in the phone space, these things are neglected until you lose market share and then they become a priority.
I had to work on a small MacOS app written in objective C at my last internship. The documentation was horrible. It was basically non-existent. I understand Swift is the primary language now, but wow, there was basically nothing in the online API reference.
Weirdly enough, this tends to be where Apple's docs are still good. They fall apart when you try to move on from it towards Swift & co.
Granted, _finding_ the ObjC old docs can be a pain in the ass, but it's possible. I've literally found answers to some of my questions in OS release notes and nowhere else; part of being an AppKit/etc developer winds up being simply knowing how to search.
Another complaint I have: depending on what era of documentation you need, you often have to qualify your searches differently - e.g, OS X vs macOS.
Has anyone else noticed that Apple has been slowly moving away from the long-form guides that were helpful at explaining core concepts? I remember once seeing a comprehensive guide on code signing, but over the years it appears to have been scrubbed from their documentation resources. In its place is a much less helpful (but prettier-looking) guide.
In comparison, I've noticed Android has FANTASTIC developer documentation. I've found full guides for everything. Even esoteric classes that are rarely used have at least a little bit of documentation.
My guess is they’re realized documentation is a huge cost center and even their own technical writers are overburdened by the churn of deprecating APIs and changing best practices. It’s worse then the JavaScript community.
I find this business decision fascinating because a good portion of their App Store revenue comes from developers. One would THINK developer relations would be a priority at Apple, but it's pretty clear that's not the case.
It was one of things that I found unbelievable when switching from Android to iOS development. The developer experience is just so much WORSE on iOS. Sometimes, it's as if Apple is actively trying to annoy developers.
For API documentation, if you can specify what you intend to build well enough to build it and validate that you have built even approximately what you intended to build, documentation shouldn't be much more work.
Based on the Android source code I've seen while working on Android projects, I think a good portion of the Android docs are generated by the inline documentation from the Android open-source project.
But on top of that, Google also produces high-quality long-form guides. Those are first-party guides, found at https://developer.android.com/. (Google maintains the Android developer site.)
Ah ok, thanks for the response! I've seen a lot of value in automatically generated docs from inline code. Perhaps that's a key baseline strategy for improvement.
Add then padding that with the long-form guides with concepts and examples.
I once owned every copy, of every generation of "Inside Macintosh."
I agree about the Android docs.
However, in defense of companies that don't like to have too much documentation around, I can tell you, from personal experience, that writing developer docs is hard, as is doing developer support.
I was a Mac beta tester back in '83, and still have a copy of the pre-release "Inside Macintosh" mimeographed the day after the original programmers wrote their drafts, filled with penciled in corrections and in some places pages of hand corrected notes. Reviewing a formal copy after edition 2 or 3, I was surprised to see a reduction in information quality and some of the key information from the penciled in notes completely missing.
The original Inside Mac was 3 volumes, after their initial printing of the "phone book edition" - all three volumes in one thick soft spine binder.
I really need to take the time to scan my copy and put it online. It's got ballpoint pen corrections from the Apple Engineers telling the beta testers various fixes.
Android HAD fantastic documentation, just like Apple had 7/10 years ago. It might not be overly apparent just yet to everyone, but Android documentation is slowly following the same path as Apple documentation, where the experience is slowly degrading, but since it was so good a few years ago, that degradation didn't creep everywhere just yet.
My coworker and me are already starting to feel the pain on various core APIs, the latest being notifications, which according to my coworker had 3 full revision, and finding documentation for the last one is hard. Storage (with Android 11 modifications) is another place where the documentation is starting to get stale. Those are not the only APIs were the documentation was poor.
In my opinion, Android documentation is at the same place iOS documentation was about 5 years ago (before they started removing entire pages from the documentation) : overall very good, but a few places were it's not up-to-par or downright horrible. I don't expect the quality to improve in the future.
Even 5 years ago, I felt that Apple's documentation was way worse than Android's.
I wonder if there is a good way to measure documentation quality...I suspect such measures will require techniques borrowed from user experience research.
Yea, i think that's correct. documentation is just another product, no different than other software.
so basically you can start asking with very common user reasearch questions such as:
* who would use our documentation?
* what would our user need the most from our documentation?
I feel like Android 11 is in a weird spot. Its a covid release and they didn't have their IO convention this year either. Seems like a lot of the big documentation dump is harder to find.
I wonder if this is on purpose and that some companies receive good documentation so that competition is kept at bay. Does Google offer some sort of training packages for Android or you can get a loan dev that knows all the quirks? I've seen this with other companies where documentation is poor on purpose so they can make extra money from training.
I don't think Google does consulting or specialized training like this for Android.
For Google Cloud Platform, they partner with other companies (like the one I work for) to help with GCP setup. This partner program was started in the last few years, so I don't think they were doing this for Android back when Android development was new.
Also, the company I work for spent a lot of time building Android apps for Fortune 500 companies, so I feel like I would have heard about it. Our clients would have benefitted from having Googlers build Android apps and train people!
I'm seeing notifications as a feature fail on my android phone too. Apparently there is simply no reliable way to get a notification at a particular time (e.g from a todo app) anymore. ON A PHONE. THE THING DESIGNED TO BEEP/RING/NOTIFY YOU OF THINGS.
Because of all the junk they've added re: battery optimization, "Adaptive AI" notifications. Even after disabling much of that, it takes a 3rd party app to get notifications reliably.
Yes! Apple used to have Technical Notes that were a deep dive into how the OS is implemented. They were super helpful in troubleshooting and optimizing for Mac OS. They haven't published anything like this in over a decade.
I suspect someone took "hiding implementation details" too seriously, and now Apple never talks about how anything works (it's all magic). You only get function's signature, and "documentation" that is basically just the function name with added spaces between words.
There are good reasons to hide the implementation details in documentation. The primary being it’s easier to keep the documentation up to date, our primary topic here. Many languages even publish class interfaces but not necessarily implementation details.
That said, a couple of example code snippets on using the interface wouldn’t hurt.
It’s always the null cases that get you... I suppose if “up to date” was the only requirement I would agree. But in reality there are many competing requirements which is why there are many degrees of documentation. Obviously internal and external documentation will be different too.
The reason to keep implementation details out of the docs is that people will rely on those implementation details, and then when their app breaks, they won't even think of looking at the documentation for updated implementation details. After all they probably have the old version all but memorized, and the app may break in a way that isn't obviously related to the implementation that changed.
Why in the world is this a random undiscoverable post in the (terribly designed) developer discussion forums rather than a Technical Note in the documentation? It would have been a TN in the past. In fact that same engineer wrote a number of old Apple TNs.
It's clear even to some within Apple that there's a need for more and better documentation, but some pointy haired boss in upper management seems to think the current situation is fine.
It might even be in their interests to drive away all but the most dedicated developers. After all, they have more apps than they'll ever need, the problem is always quality.
When I worked at Apple in the mid 90's, DTS had to hire someone to go around to every engineering team to collect what they had change so we could write a tech overview of an OS release, otherwise no one would have known what changed. But then was when Apple was going out of business.
Yes, and this is a really shame. Several years ago I was able to become an iOS developer almost completely by reading through Apple's docs and then building a couple of projects on my own. I had a checklist of the programming guides to work my way through from Objective-C, to App Programming, to view controllers, and on. Over the years I found it more and more frustrating to truly understand new frameworks as the documentation changed. iOS development is now a small portion of my job and the lack of good resources is making it hard to stay up to date.
And even when there's no documentation, or when it isn't enough, you can just always dive into AOSP sources and figure out whatever needs to be figured out. They've recently made this more convenient too: https://cs.android.com
No such luck for iOS. Best you can do is poke at binaries with a disassembler.
I have been frustrated many times after stepping into a system function on iOS, only to be greeted with a mountain of assembly instructions. It was one of the first grievances I had with iOS development, coming from Android.
On the other hand, it's been a great opportunity to learn how ARM works!
Oh yes, I remember the programming guides! When a friend of mine and I wrote the text editor Tincta we spend days to go through the typesetting, font, glyphs documents. We didn't really use it but we learned so much (we were still students and couldn't imagine how complicated all that is). Same for the maps and location APIs. You could really appreciate all the work and design that went into the APIs.
Now I feel some of that information is hidden in WWDC videos but it's not the same.
I also had good experience with the Android documentation, same (as the article stated) for PHP and most of Microsoft.
I have been trying to optimize a initContainer written in NodeJS and one of the experiment I am trying out is to rewrite it in .NET Core and Microsoft's documentation has been pretty good - it is clear, well organized, gives you examples for each API and there are how-tos for things that people typically care about - the architecture docs linked from here for e.g. https://docs.microsoft.com/en-us/dotnet/
I find the Python docs and tutorials good as well. But that's to be expected for mature language/ecosystem like Python.
Good documentation is a lot of work and skill and it's a thankless job for the most part. So it's really amazing when organizations / OSS communities get it right consistently.
Microsoft has put lots of effort into their docs in the past couple years, and it's pretty great.
Under the "Version" dropdown you can flip to see the same docs in a specific version or platform (Framework vs Core), and this is pretty helpful for porting/upgrading code, as well as coming from a Google search or Stack Overflow link -- you can easily get to the docs for the version you're working with.
The other great thing they've done is published all the .NET code on https://source.dot.net, so you can dive into the code for ConcurrentQueue<T> [1] for example. I sometimes find looking at the source is a faster way to answer a specific question about how something works vs reading through several pages of documentation, where the nuance I care about is noted in a "Remarks" section which is easily missed.
Yes, the version dropdown is a godsend especially for .NET as there are many variations - If I want to see if the API exists or is different on say .Net Core vs .Net standard this makes it a piece of cake.
Also wasn't aware of the source browser - some questions are best answered by - use the source, Luke - and you might get better ideas for your own code from there :)
Personally I keep a .NET decompiler on my taskbar. I was about to say I like being able to find all references and usages of internal variables, but I see now the site does a pretty good job. I also like directly seeing how my code utilizes the library functions (not just the .NET libraries, sometimes nuget packages too). The decompiler also removes ambiguity of "what code is actually being ran". ILSpy has worked nicely for me, it has the extra perk of having nice integration with LINQPad (another must-have for .NET developers)
ILSpy + LINQpad is my go-to as well, and I actually still use ILSpy more often than source.dot.net. It's nice to be able to send a link to someone else though, and the site is well done, fast, and has a great domain. :)
Is there an offline version of that documentation? One of the best things about Java is that you can install the documentation package (depending on your distribution, it's something like java-11-openjdk-javadoc) and the source code package (something like java-11-openjdk-src), and have an offline copy of the full documentation which you can open directly in your web browser and IDE.
I'm not so sure about that last part. My guess would be that this is down to the difference in incentives between an open-source project and a profitable enterprise. In such a way that we may even expect this to be the common case, rather than an anomaly.
Every doc writer Apple hires has to go on a P&L statement somewhere, their existence must be justified every quarter or so, etc. As others have noted, associating this work with the value it generates is notoriously difficult. Of course, some companies may have the kind of culture that understands the value of this work and keeps them around, but open-source projects can accept contributions from whoever offers them without regard for such bureaucratic concerns.
Basically, if you write some docs for my open-source project I don't need to pay for your healthcare insurance. The barrier to entry may also be lower for the same reason- if you write some docs, the pull request can be simply merged in. Hiring an employee is a much more involved affair than adding a contributor to the Contributors list in Github.
I could have sworn I read a comment on this site a few years ago where someone claimed they had to submit a support ticket in order to grt documentation for some Apple API.
Having run into something similar just recently [0], having any documentation is still (slightly) better than no documentation at all. As a stark example, macOS has a built-in sandboxing CLI tool called sandbox-exec (originally called Seatbelt), but the man page simply says it's deprecated, as far back as I could find them. Mind you, the same tool is used heavily by macOS internally, and has been around ever since Leopard [1]. Some of the best documentation is by engineers at Google, Mozilla, and others, who have just reverse engineered the thing.
I don’t personally have much experience with Apple’s documentation in particular, but as a general topic, increasing the quality of documentation seems to be one of the least complicated ways to improve a platform. For all the complaints people have about how hype-oriented the frontend web world can be at times, it seems clear to me that there’s usually some correlation between hype factor and simple examples/clear documentation, and that this excitement can make people move to a new technology much faster. It’s really hard to understand why Apple wouldn’t spend the necessary resources to bring developers along at a faster pace.
I am 100% convinced that Stripe's success is at least partly due to their attention to documentation and design. Their documentation and knowledge base should be used in case studies on how to succeed as a saas.
Honestly, reading the headers is the only way to understand iOS, macOS, and iPadOS properly.
I find that the older I get, the more _code is my documentation._ Particularly for things like Python's matplotlib, once you do more than put lines or scatter plots together, you _have_ to understand how the code actually works.
Of course, that's difficult when all you get is header files, but still...
"Code is the documentation" has to have boundaries though, or else you'd have to understand the entire system down to the instruction set in order to print hello world.
Within a small/medium codebase, code is documentation is mostly okay, but for libraries and abstractions you really ought to have solid API docs.
I get the mindset and am very much a read-the-code person as well but my go-to example for this kind of thinking is that reading the code in lieu of a written summary/guide, etc is like trying to understand a book where the chapters and paragraphs are mixed around. It's possible and the ability to do so worthy of pride but it's clear that a succinct summary in one place would be far easier and time-efficient.
Not to say that heavy documentation like this is perfect of course. It just seems like the complexity of the read-the-code solution is sometimes glossed over.
Right, that’s the thing isn’t it—sometimes an abundance of documentation is actually not a good thing. matplotlib is a good example, its documentation fails to convey the common arguments and to what degree they are universal or not; reading the code is really the easier way in the end.
I've been a technical writer for ~8 years (3 at a startup, 5 at Gooble). I don't know Apple's situation but here's my guess:
> Is the documentation team too small? (Likely.)
Documentation is weird because there seems to be widespread agreement among developers about how lacking it is (and conversely I think it's safe to say how important it is for job success) yet technical writing is almost always understaffed, no matter what size company you have. Part of it is that it's really hard to show a causal link between the docs we create and developer success. I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links at the bottom of pages, followed by an opportunity to provide freeform feedback. If developers started using those consistently and leaving testimony about how the docs helped them it would be a lot easier to prove the value of docs. This is especially true when you operate at a big, platform-level scale, as is the case on https://web.dev (what I work on) and these Apple API docs. Pageviews give us a rough idea of the demand for certain ideas but don't tell us anything about whether our docs are actually useful.
(As an aside, in some situations it's easier to justify the technical writing team's existence; e.g. your technical writer specifically creates docs in response to support requests and the support team is able to just link customers to the docs rather than re-answering the same question over and over; or you have access to "customer's" code and are able to show that they are following the best practices / use cases you mention and avoid anti-patterns you warn about)
I'll leave with a suggestion because I don't have a horse in this race. If this situation is so bad; your best option might be to create a community-managed MDN-style resource for the Apple ecosystem. I would suggest focusing it on 1) API reference documentation and 2) examples (MDN puts the examples within the API reference pages, that would probably work here).
Another route could be more of what these people are already doing: make a lot of noise until Apple realizes how bad the situation is. I imagine if you can prove that you're leaving their platform because the situation is so bad, that might wake them up.
(No disrespect to Apple people; I know how tough this situation is; just trying to provide constructive feedback for the broader community)
We get 1-5% response rates (which is normal; I've done this on a few sites now) but we have enough scale where we're getting enough feedback that I can use the data to identify the worst docs. The basic methodology is to prioritize the pages with the most pageviews + lowest helpfulness scores. Of course there's a risk that we're prioritizing our work based on data that isn't indicative of our overall audience and due to the general nature of the question ("was this page helpful?") we also don't know how exactly the doc is unhelpful but in practice it's usually easy to make an educated guess (e.g. one of the Lighthouse guides is very low rated, and when I checked on it recently I discovered it's just a stub with very little guidance; so the educated guess is to add more guidance to the page; and then a few months from now I can see if the ratings have improved). Another good pattern is to provide a freeform textbox for feedback. The only reason we don't have that is because Gooble considers it PII and I have to jump through hoops to store that data properly.
> I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links at the bottom of pages, followed by an opportunity to provide freeform feedback.
Whilst this is great, I think most people perceive documentation differently. Rarely does documentation delight me in the sense that I'd leave feedback. Generally, my interaction with documentation is one of "It works as expected"; "pretty bad but I still managed"; or "bad, didn't help, or didn't exist".
The thing that has the most effect on my is the last one. That is what will get me to drop a system. The first one "it works as expected" comes with a little but of surprise and delight. But, perhaps paradoxically, even though it surprises me, it still only meets my expectation. With a 'was this helpful' prompt, I'd need to click "it was helpful" on every successful search of documentation I ever do. This seems still too unremarkable for me to explicitly mention it was helpful.
Yup I know it's a tall order / unrealistic but I'm just trying to provide context as to why documentation might be systematically underfunded (lack of causal chain proving its value). Your response is totally understandable but it also demonstrates why the situation probably won't change any time soon.
establishing a DSAT metric is still powerful. Lifting a key feedback metric from "this is bullshit" to "this is ok" is something you can sell management on
As someone who was in the so called "DevOps" position for years, I'm slowly becoming tired of asking management for "give me a technical writer, even half-time, instead of another dev/ops person" :(
> technical writing is almost always understaffed
> it's really hard to show a causal link between the docs we create and developer success
Amen to that. IMO good documentation is incredibly valuable, but not in a way that aligns with business priorities. At my current job, we hear, repeatedly, that our documentation is poor, and that we need to improve it. Execs echo this sentiment, but the status quo doesn't budge.
Internally, we have about a 10:1 engineer:tech writer ratio (in a small-ish org--I assume the gap is even wider in larger orgs), and the writers are all generalists, covering every product from top to bottom. In practice, this means that engineers are asked to draft the bulk of documentation, and the writers scramble to at least copy-edit it.
Engineer-drafted documentation often isn't great, unfortunately, for several key reasons:
- Writing software is very different from using software. Engineers often don't use their own products, and writing about something you don't actually do is hard.
- It's very easy to omit details that are important for novices when you are an expert. Engineers usually have a great deal of knowledge about their own software in their brain already, because they wrote it, and cannot magically forget everything they know when asked to write documentation for someone who doesn't have that knowledge already.
- Writing effective, clear prose is hard, especially when writing about complex technical subjects for an audience with varying skill levels. Engineers don't spend the bulk of their time writing prose, and it's often not their strongest skill.
Personally, I have a mix of both skillsets because of a weird career path, but while I actually like writing documentation and am arguably better at it than writing software, there's no good reason to pursue that path: I can easily get double the salary in an engineering position as I can in a writing position, despite being a rather mediocre engineer. So I do software engineering :shrug:
It's also very hard to get in the minds of the developers who rely on the API/tool and create documentation that mirrors their mental models, background, language usage, etc.
With Chrome DevTools (I wrote/maintained pretty much all the official docs for about 3 years) it was a bit easier because I had a huge repository of direct user experience to draw from: the thousands of Stack Overflow questions about DevTools
> the writers are all generalists, covering every product from top to bottom. In practice, this means that engineers are asked to draft the bulk of documentation, and the writers scramble to at least copy-edit it.
This seems like an organizational/staffing mistake. In other engineering orgs you'd see these roles filled by applications engineers, who dogfood while evangelizing the product and writing its technical documentation. Ambiguity or questions are handled by conversations with the engineers that built it.
I do think hiring application engineers with that kind of job description is one solution, but so is having a larger number of technical writers so they don't need to be generalists.
I'll admit that I'm pretty bad at formal documentation myself, but I've been wanting to improve that lately. So as a technical writer do you have any suggestions/links to material for learning the trade or even some sort of formal training courses for professional development that I can pass to my employer?
To be honest, was this helpful button is rather vague and I usually ignore it because it doesnt seem to be the right question or rather its a request for feedback I don't know helps me or not.
I advocate for "was this page helpful?" being the standard question across docs sites because ultimately it does reflect the purpose of documentation (to be helpful in one way or another, which usually means helping you complete a task or understand a concept) and because using the same question on all sites enables us to benchmark and compare. I once ran an A/B test on the same page where 50% were prompted "was this page helpful?" and the other 50% were prompted "was this page useful?" and the results were different to a statistically significant degree which suggests that even minor rephrasings skew the results, so we need to all use the same terminology.
> its a request for feedback I don't know helps me or not
Yes I'm aware that readers aren't incentivized to respond which explains why it's rare to get higher than 5% response rate. This situation is a microcosm for documentation's overall problem: we can't find incentives for people to voluntarily and consistently confirm the value we provide and we don't have any other means to prove the causality.
"Part of it is that it's really hard to show a causal link between the docs we create and developer success"
Yep, high traffic to a dev doc web page is ambiguous. Is it because it's really good? Is it because it's bad and people keep coming back trying to understand it? Or is the documentation fine but the API being documented is just hard to use?
> I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links
And when you do this, DO NOT serve up the feedback form/popup from some advertising domain, otherwise developers with ad lockers (many, if not most) won't even see it.
Apple seems like they are willing to double down on SwiftUI/UiKit with Catalyst.
It's getting less simple for new APIs/features but at least Apple's docs have straightforward hierarchy, even with two separate languages. Duplicate APIs usually get deprecated, like the old ALAssets photo library API.
Try building an app in .NET. There are dozens of different breadcrumbs you can follow on the MS docs for varying versions of .NET, Windows, and frameworks with radically different feature parity and UI systems. Virtually everything you google when building a .NET app has to suffixed with a bunch of identifying information for which libraries and versions you are targeting.
Open source has a serious advantage in this regard because communities tend to congregate around project and documentation styles that are consistent with similar projects, so you already have an intuition for how to navigate a new repo. I find React Native documentation especially easy to parse, although sometimes missing features or examples.
OSs have it tough because their docs aren't tailored specifically to each framework and domain space. But maybe they should be. I think if engineers felt more like they owned their product's documentation, layout, and structure like at smaller companies, they'd be more inclined to make it just right. The SwiftUI specific tutorials are great.
Is it really an asset to not have documentation for old frameworks or versions? Some people have customers on old hardware and legacy code using old APIs that they might need to integrate with, it's useful to be able to find out how that stuff behaves.
That's the thing, it's all still there, but it's abundantly clear based on the pages and the list of supported OSs/platforms whether you can use it, and what the new API is.
For me, a large part of React Native's appeal is the docs giving me a clear path to make stuff and a fairly public development process. Sure it is also an extra layer of trouble, but I prefer the trouble I can engage with (RN) over the risk of being stranded in the unknowable (Apple).
True, and I do like this a lot. There's a great ecosystem, and the examples are usually pretty good.
But it's also just as easy to get stranded with missing features or features that aren't on both Android and iOS. I did a bunch of geolocation and mapping a while back and I had to write my own support for things like heatmaps. This was eventually merged into the react native maps library, but it is something that can happen if you're doing anything slightly exotic.
I actually disagree completely. Your answer does not relate to my comment at all.
This is about “Apple losing the functional high-ground” (which they clearly had at one point) in terms of design, architecture and general “DX”.
All in comparison to its own previous high quality.
In terms of quality of products they still are best in their respective class IMHO. Security, usability and durability are still great/good enough. This has nothing to do with marketing.
Marketing is necessary to bring up as Security and durability claims have been debunked enough times. Perception isn't reality, but similar to Tesla and Jeep owners they have high satisfaction despite objectively poor qualities.
You only need to try giving your grandparents a iphone to realize usability claims are greatly exaggerated.
The n=1 sample sounds like a normal beginner that wants to buy high-end equipment for a new aspiration. Doesn't mean much. My n=1 is for unix architecture and reliability. Probably the same for many devs.
I literally googled a few hours ago for "Why is Apple documentation so shit?"
I mean, look at SwiftUI. Conceptually it's great, but it is also fucking buggy as hell, and I think one of the main reasons is that the developers themselves don't have good documentation available. The best documentation so far I found is this, but it's third-party: https://www.objc.io/books/thinking-in-swiftui/
SwiftUI is not great in any sense, other than looking great to people who've never written non-trivial software. When your criteria for 'great' is whatever 'content creators', 'software journalists' (email newsletter 'creators') and apple's marketing team pump out this week, 'great' is anything a marketing firm puts dollars behind that seems 'cool' and 'fresh' and 'hip', or is it 'dope' this week?
It is quintessential form over substance - like Apple's fucking 'butterfly' keyboards.
SwiftUI is butterfly keyboards of software - wait until you want to write non-toy code with it, you'll be needing 'hack #235 by content creator #563' to make trivial features possible.
I've actively made an effort to learn SwiftUI this week so I can write my software quicker. I don't want to spend hours on displaying some styled list in my apps, that should be done in a few minutes. SwiftUI allows for that. Once all the bugs are gone, that is. So far, I've spent a lot of time on SwiftUI's bugs. Luckily, you can always dive down to UIKit if all else fails.
SwiftUI brings concepts from React and Flutter to the Apple ecosystem, which is great. It's especially great for people writing non-trivial software, because we don't want to spend our time on doing trivial stuff.
Ah, we are so lucky to have a framework full of language features that only it uses and an ability to drop down and learn a whole other suite of frameworks that work completely differently to achieve the same task!
I've been so lucky to have to learn near a dozen programming languages in the span of less than a decade to write CRUD apps that appear on screens and do the same thing on each platform slightly differently.
I only hope to be more lucky in the decades to come, maybe I'll have to learn two dozen new languages and three dozen new frameworks to write CRUD apps that show up on computer screens.
I am 'doing' real software - I saved up my money writing CRUD and quit as soon as I could afford to.
What I am personally doing in no way negates the fragmentation that is present. SwiftUI is the latest contributor to never-ending CRUD hell and I am merely informing the young and impressionable, that SwiftUI is not your friend - it is your anti-cross-platform, proprietary, closed source devil spawn (being dramatic for fun :)) and if you ever want to start solving real world problems instead of learning the latest framework that does what we did 20 years ago but 5% better this time, you better listen real careful to annoying debby-downers like me, Joe Armstrong (RIP), Rich Hickey etc who got fed up with the corporate matrix and went a different way.
I had the pleasure to attend a talk given by Joe Armstrong. For some reason he was always looking over to Phil Wadler, apparently looking for approving nods, but there were none to be found :-)
I hear what you are saying. I also find it unfortunate that something simple like UI is so fragmented. But then again, maybe UI is not so simple after all. The current paradigm that SwiftUI copies and evolves is that of React, and it just didn't exist 20 years ago. Funny also that this new paradigm was invented for the web first. While a lot of web stuff is crappy indeed, this is one of those examples where it produced a superior paradigm that is now copied and evolved outside of web as well, for example by SwiftUI, also by Flutter.
Is it progress, though? If the React paradigm is so much better, you'd expect some kind of UX renaissance stemming from its adoption. Instead, we're still struggling with Electron-based apps that are "prettier" but less productive than what we had 20 years ago, back when they were written in UI frameworks that barely even had any data binding at all.
SwiftUI is “great” for a calculator demo or a to-do list app. Otherwise it’s just a gimmick, but Apple had gotten anxious about ReactNative and had to make something palatable for the webdevs... Although making SwiftUI mandatory for home screen widget extensions is very concerning, and on the long run they’re probably shooting themselves in the foot by pushing this buggy toy framework...
Why would they improve the documentation? It's not like you have a choice anyway, you will have to figure out, since you cannot ask your customers to switch to another mobile platform... They really don't give a shit about developers. I'm a backend developer, their In App Purchase system is the worse API I have been unfortunate to work with (and it's much better than what it used to be)
Here's a contrarian view of this (deplorable) situation, from someone who developed for Microsoft platforms for years. The low quality of the documentation has two reasons:
* Protectionism: The poor documentation defends expert third party developers against competition from new entrants. It ensures a shortage of competent developers and so enhances the revenue of established experts.
* Low commitment: The publisher (Apple) is unwilling to make the functional commitments implied by good documentation. Once the documentation says "this does that" it's harder to change "this" to do something else.
In the distant past, Apple teamed up with the publisher Addison-Wesley to create and publish high quality documentation. They could certainly do so again, with A-W or O'Reilly or whoever.
But they won't do it as long as they have business reasons not to. They have sufficient control over their marketplace to refuse to do this and get away with it.
> The poor documentation defends expert third party developers against competition from new entrants. It ensures a shortage of competent developers and so enhances the revenue of established experts.
Why in the world would Apple want to ensure a shortage of competent developers — for apps on Apple's platforms! — or protect third party experts?
Apple slowly wants to pump out their own apps that do everything to maximize their recurring subscription revenue. Why settle for 30% when you can take 100%.
Why do they want dev skills to go at a premium price? For one thing, they do not have any shortage of apps coming in to their app store. They're no longer in the business of begging people to deploy apps. Instead, they're in the business of vetting the apps people submit.
Raising barriers to entry for new developers is a cost-cutting measure for them. And fewer apps on the store, even at the margins, is a revenue enhancer for incumbent app developers.
This may or may not be an explicit factor in their decision making. But it surely contributes to their lack of focus on docs: better docs will improve their profitability not at all.
A middling language with exceptional documentation can sometimes be more effective than an exceptional language with spotty documentation. The friction of acquiring sufficient context to get up and running with a language is a huge part of any technical task IMO.
Hah the nightmare to get CallKit working. The only thing you could do is take a working example application and step by step wrap your application around it.
Because taking your existing VoIP application and inserting CallKit behavior breaks in so many mysterious and undocumented ways that I really had to tell a client it wasn't going to happen with his existing application within the allocated budget.
Just to get the fancy Apple call screen!
And of course only FaceTime can take video calls straight into video from the lock screen, so you have to explain after it works why nobody can see each other.
I don't think Steve would have allowed this to happen. Developers are way too important part of the whole "where the money comes from?" question. He would have noticed the complaints before anyone wrote a blog about it.
Docs for the 68k Mac were abysmal. There was a collection of books entitled "Inside Macintosh" that were nearly impenetrable, and only scratched the surface of the elaborate class libraries. Instructions for creating "Hello World" on the Mac were dozens of pages long.
From what I've read, Jobs certainly understood the importance of software, but only great software. He didn't want the Apple ecosystem to become loaded up with crapware like on the IBM, or on the Apple ][ for that matter. So, if a small time developer couldn't write and distribute a crude but useful app, so be it. Favored developers probably didn't fare any better with the documentation, but help was a phone call away.
This was the "closed box" philosophy that I don't think has changed much over the years.
The irony was that "crappy but open" attracted more developers than "wonderful but closed." This is why apps such as assemblers for microcontrollers were written for MS-DOS. Essentially, even after the introduction of MS Windows, the ability to write for DOS provided a way to create and share simple apps.
I still have my copies of Inside Macintosh, I consider them to be examples of good documentation.
They didn't cover "class libraries". I don't have copies of whatever documentation was provided with MacApp, I do have a Think-C manual that describes their environment.
Thanks. I appreciate the counterpoint. I don't remember when class libraries became part of the Mac programming experience, but like you say it might not have been with the original docs.
This isn't an apple thing. Its industry wide. Much of the good documentation that exists is stuff that was written 20+ years ago by actual technical writers and is still being maintained.
AKA the windows API/etc documentation, linux man pages, etc.
The vast majority of modern documentation is worthless autogenerated garbage when it exists. It lacks good examples, meaningful overviews and functional diagrams. In many cases its woefully out of date because someone rejiggered an API and didn't bother to even update the inline documentation.
One of the better examples of recent documentation is the core rust docs/books. Even then because the rapid release cycles no one publishes an updated "Learn Rust" book for every release, complete with boxes explaining what has changed since the last release. And god help you if you dig to far into the library ecosystem.
I think this is caused by one single problem. Documentation isn't sexy and no one is paying technical writers to do the grunt work anymore. Opensource is a large part of this problem, but the commercial guys have discovered they can save a few hundred thousand a year by simply not having a documentation team, and it doesn't appear to affect them much. A couple youtube tutorials and they are done.
You can see this in the evolution of software, etc. In the 1970's you got large paper manuals which covered every technical aspect of the machine/software. The users were expected to use their brains. Then in the 1980's it all transitioned to "user documentation" which was more focused on manuals that explain how to use the product, by removing the how it works part. Then in the 1990's it started moving to digital copies on disk, and the product came with a 3-4 page manual explaining how to bootstrap enough to read the rest of the docs. In the 2000's it all moved online and became more "marketing" than users guides. In the 2010's they stopped even that. Now you get a phone/software/computer your lucky to even get a piece of paper that tells you how to turn it on, charge it, or install it. Even ms doesn't publish a complete guide to all the magic swipes and keystrokes that are supported by their new shell.
Function description, supported version information, header-file and library file information, meaningful return code documentation, links to an overview of the system wait behaviors, documentation about what happens in low power situations, links to example code using the function, differences in behavior between differing versions, it goes on and on.
Can you point to something you think is better?
PS: I should point out, I have paper copies of the win32 api from the early 1990's that are falling apart from the use they got.
That is a good one too, but its not in as bad of shape as my official win32 guides from MS. My copy of Volume 2 of the win32 reference has nearly as much tape as paper, although I haven't picked it up in probably 10 years.
edit: Holy crap, in an effort to find an online picture of the volume, i noticed that amazon is selling the slightly newer ones for over $800. Looks like I should have taken better care of it.
Arr, sorry I misread your comment. I am on your side when it comes to Windows API. But I am not sure if it's a thing of the past. Imo Microsoft is pretty good when it comes to documentation. The way of presentation can be improved, but I really appreciate it. I think it's a culture thing and that culture seems to be different within Apple... I think this is also visible when it comes to their app store policies....
He was trying to find out whether it's safe to call a particular iOS API function off the main thread. Obviously, the docs didn't say. He googled a bit and found a support forum where someone had asked. An Apple engineer responded: "I don't know, but I'm looking at the code, and there sure are a lot of locks!"
The particularly sad cases are when The Great API Renaming took things with older names that had good documentation and failed to copy the documentation to the new ones! Deprecations usually don’t indicate their preferred replacements either. As has been the case for years, docs may exist if you know where to look.
As for SwiftUI (documentation aside) it is very powerful, even with its current API holes, and the benefits are huge. You do have to slightly rethink how you might approach certain things but ultimately SwiftUI produces shorter and cleaner code with no XIBs. (Hint: If you do end up with pages of hacky work-around code, you’re doing it wrong and should stop.) I have no doubt it will be the primary/preferred mechanism in 1-2 years.
347 comments
[ 3.6 ms ] story [ 285 ms ] threadThanks. 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.
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)
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.
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).
While I'm not an iOS dev I have seen a trend where people have stopped putting in dates of their coding tutorials.
Get ready for documentation subscriptions. I wish I were joking.
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.
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.
https://docs.microsoft.com/en-us/dotnet/api/system.string.su...
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.
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 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.
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...)
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.
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...
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.
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.
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.
You seem to be arguing against a negative value judgement which I did not make, or even suggest.
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).
I thought that was what the $99/year was for.
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:
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.
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
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.
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.
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.
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.
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.
https://developer.apple.com/documentation/swiftui/progressvi...
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?
It seems that as you get larger in the phone space, these things are neglected until you lose market share and then they become a priority.
But.. this article is completely correct about SwiftUI documentation.
Granted, _finding_ the ObjC old docs can be a pain in the ass, but it's possible. I've literally found answers to some of my questions in OS release notes and nowhere else; part of being an AppKit/etc developer winds up being simply knowing how to search.
Another complaint I have: depending on what era of documentation you need, you often have to qualify your searches differently - e.g, OS X vs macOS.
In comparison, I've noticed Android has FANTASTIC developer documentation. I've found full guides for everything. Even esoteric classes that are rarely used have at least a little bit of documentation.
It was one of things that I found unbelievable when switching from Android to iOS development. The developer experience is just so much WORSE on iOS. Sometimes, it's as if Apple is actively trying to annoy developers.
It's a tiny cost center, in the grand scheme of things. As it is they probably spend less than they spend cleaning the glass at Apple Park.
Sadly, they seem to have stopped writing these at around 2015...
[1] https://developer.apple.com/library/archive/documentation/Co...
But on top of that, Google also produces high-quality long-form guides. Those are first-party guides, found at https://developer.android.com/. (Google maintains the Android developer site.)
Add then padding that with the long-form guides with concepts and examples.
I so often need to do a simple thing, find a function that looks about right, and the documentation for it says literally nothing about how to use it.
I agree about the Android docs.
However, in defense of companies that don't like to have too much documentation around, I can tell you, from personal experience, that writing developer docs is hard, as is doing developer support.
Keeping them up to date is also a challenge.
I call it "concrete galoshes": https://littlegreenviper.com/miscellany/concrete-galoshes/
I got my first Mac in '86 (a Mac Plus).
My first copy of Inside Macintosh was the hardcover. I think it was two volumes, back then.
My coworker and me are already starting to feel the pain on various core APIs, the latest being notifications, which according to my coworker had 3 full revision, and finding documentation for the last one is hard. Storage (with Android 11 modifications) is another place where the documentation is starting to get stale. Those are not the only APIs were the documentation was poor.
In my opinion, Android documentation is at the same place iOS documentation was about 5 years ago (before they started removing entire pages from the documentation) : overall very good, but a few places were it's not up-to-par or downright horrible. I don't expect the quality to improve in the future.
I wonder if there is a good way to measure documentation quality...I suspect such measures will require techniques borrowed from user experience research.
I would start with a checklist:
- is it complete and consistent
- is there a description to every important piece
- working examples
... and if this is complete, you can measure all you want, but I would start with the basics.
For Google Cloud Platform, they partner with other companies (like the one I work for) to help with GCP setup. This partner program was started in the last few years, so I don't think they were doing this for Android back when Android development was new.
Also, the company I work for spent a lot of time building Android apps for Fortune 500 companies, so I feel like I would have heard about it. Our clients would have benefitted from having Googlers build Android apps and train people!
Because of all the junk they've added re: battery optimization, "Adaptive AI" notifications. Even after disabling much of that, it takes a 3rd party app to get notifications reliably.
I suspect someone took "hiding implementation details" too seriously, and now Apple never talks about how anything works (it's all magic). You only get function's signature, and "documentation" that is basically just the function name with added spaces between words.
That said, a couple of example code snippets on using the interface wouldn’t hurt.
That's NOT a "good" reason in any sense.
That's a terrible reason, which no-one in a team leader or above position should ever sign off on.
Wolfram Documentation on Mathematica is excellent in my humble opinion. Here is a function I use very often, convolve.
https://reference.wolfram.com/language/ref/Convolve.html
Notice how the interface is very well described, there are examples on how to use it, but there are no implementation details.
That's not an "easier to keep documentation up to date" type of thing ;), but is definitely an example of good documentation.
Unlike the Apple approach mentioned above. :( :( :(
https://developer.apple.com/forums/thread/663858
Why in the world is this a random undiscoverable post in the (terribly designed) developer discussion forums rather than a Technical Note in the documentation? It would have been a TN in the past. In fact that same engineer wrote a number of old Apple TNs.
It's clear even to some within Apple that there's a need for more and better documentation, but some pointy haired boss in upper management seems to think the current situation is fine.
But writing quality apps requires quality API documentation. I don't know how developers fumbling around in the dark can result in quality apps.
Being "dedicated" to Apple platforms is not the same as being dedicated to quality.
No such luck for iOS. Best you can do is poke at binaries with a disassembler.
On the other hand, it's been a great opportunity to learn how ARM works!
Now I feel some of that information is hidden in WWDC videos but it's not the same.
I also had good experience with the Android documentation, same (as the article stated) for PHP and most of Microsoft.
The documentation has lots of outdated stuff that only gets updated across Medium, StackOverflow, bug tracking comments, twitter posts, /r/androiddev.
Header docs are more likely to be kept in sync with the API than whatever they have online.
API docs example -https://docs.microsoft.com/en-us/dotnet/api/system.collectio...
I find the Python docs and tutorials good as well. But that's to be expected for mature language/ecosystem like Python.
Good documentation is a lot of work and skill and it's a thankless job for the most part. So it's really amazing when organizations / OSS communities get it right consistently.
Under the "Version" dropdown you can flip to see the same docs in a specific version or platform (Framework vs Core), and this is pretty helpful for porting/upgrading code, as well as coming from a Google search or Stack Overflow link -- you can easily get to the docs for the version you're working with.
The other great thing they've done is published all the .NET code on https://source.dot.net, so you can dive into the code for ConcurrentQueue<T> [1] for example. I sometimes find looking at the source is a faster way to answer a specific question about how something works vs reading through several pages of documentation, where the nuance I care about is noted in a "Remarks" section which is easily missed.
[1] https://source.dot.net/#System.Private.CoreLib/ConcurrentQue...
Also wasn't aware of the source browser - some questions are best answered by - use the source, Luke - and you might get better ideas for your own code from there :)
Every doc writer Apple hires has to go on a P&L statement somewhere, their existence must be justified every quarter or so, etc. As others have noted, associating this work with the value it generates is notoriously difficult. Of course, some companies may have the kind of culture that understands the value of this work and keeps them around, but open-source projects can accept contributions from whoever offers them without regard for such bureaucratic concerns.
Basically, if you write some docs for my open-source project I don't need to pay for your healthcare insurance. The barrier to entry may also be lower for the same reason- if you write some docs, the pull request can be simply merged in. Hiring an employee is a much more involved affair than adding a contributor to the Contributors list in Github.
[0] https://www.karltarvas.com/2020/10/25/macos-app-sandboxing-v...
[1] https://www.chromium.org/developers/design-documents/sandbox...
I find that the older I get, the more _code is my documentation._ Particularly for things like Python's matplotlib, once you do more than put lines or scatter plots together, you _have_ to understand how the code actually works.
Of course, that's difficult when all you get is header files, but still...
Within a small/medium codebase, code is documentation is mostly okay, but for libraries and abstractions you really ought to have solid API docs.
Not to say that heavy documentation like this is perfect of course. It just seems like the complexity of the read-the-code solution is sometimes glossed over.
> Is the documentation team too small? (Likely.)
Documentation is weird because there seems to be widespread agreement among developers about how lacking it is (and conversely I think it's safe to say how important it is for job success) yet technical writing is almost always understaffed, no matter what size company you have. Part of it is that it's really hard to show a causal link between the docs we create and developer success. I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links at the bottom of pages, followed by an opportunity to provide freeform feedback. If developers started using those consistently and leaving testimony about how the docs helped them it would be a lot easier to prove the value of docs. This is especially true when you operate at a big, platform-level scale, as is the case on https://web.dev (what I work on) and these Apple API docs. Pageviews give us a rough idea of the demand for certain ideas but don't tell us anything about whether our docs are actually useful.
(As an aside, in some situations it's easier to justify the technical writing team's existence; e.g. your technical writer specifically creates docs in response to support requests and the support team is able to just link customers to the docs rather than re-answering the same question over and over; or you have access to "customer's" code and are able to show that they are following the best practices / use cases you mention and avoid anti-patterns you warn about)
I'll leave with a suggestion because I don't have a horse in this race. If this situation is so bad; your best option might be to create a community-managed MDN-style resource for the Apple ecosystem. I would suggest focusing it on 1) API reference documentation and 2) examples (MDN puts the examples within the API reference pages, that would probably work here).
Another route could be more of what these people are already doing: make a lot of noise until Apple realizes how bad the situation is. I imagine if you can prove that you're leaving their platform because the situation is so bad, that might wake them up.
(No disrespect to Apple people; I know how tough this situation is; just trying to provide constructive feedback for the broader community)
Whilst this is great, I think most people perceive documentation differently. Rarely does documentation delight me in the sense that I'd leave feedback. Generally, my interaction with documentation is one of "It works as expected"; "pretty bad but I still managed"; or "bad, didn't help, or didn't exist".
The thing that has the most effect on my is the last one. That is what will get me to drop a system. The first one "it works as expected" comes with a little but of surprise and delight. But, perhaps paradoxically, even though it surprises me, it still only meets my expectation. With a 'was this helpful' prompt, I'd need to click "it was helpful" on every successful search of documentation I ever do. This seems still too unremarkable for me to explicitly mention it was helpful.
Amen to that. IMO good documentation is incredibly valuable, but not in a way that aligns with business priorities. At my current job, we hear, repeatedly, that our documentation is poor, and that we need to improve it. Execs echo this sentiment, but the status quo doesn't budge.
Internally, we have about a 10:1 engineer:tech writer ratio (in a small-ish org--I assume the gap is even wider in larger orgs), and the writers are all generalists, covering every product from top to bottom. In practice, this means that engineers are asked to draft the bulk of documentation, and the writers scramble to at least copy-edit it.
Engineer-drafted documentation often isn't great, unfortunately, for several key reasons:
- Writing software is very different from using software. Engineers often don't use their own products, and writing about something you don't actually do is hard.
- It's very easy to omit details that are important for novices when you are an expert. Engineers usually have a great deal of knowledge about their own software in their brain already, because they wrote it, and cannot magically forget everything they know when asked to write documentation for someone who doesn't have that knowledge already.
- Writing effective, clear prose is hard, especially when writing about complex technical subjects for an audience with varying skill levels. Engineers don't spend the bulk of their time writing prose, and it's often not their strongest skill.
Personally, I have a mix of both skillsets because of a weird career path, but while I actually like writing documentation and am arguably better at it than writing software, there's no good reason to pursue that path: I can easily get double the salary in an engineering position as I can in a writing position, despite being a rather mediocre engineer. So I do software engineering :shrug:
With Chrome DevTools (I wrote/maintained pretty much all the official docs for about 3 years) it was a bit easier because I had a huge repository of direct user experience to draw from: the thousands of Stack Overflow questions about DevTools
This seems like an organizational/staffing mistake. In other engineering orgs you'd see these roles filled by applications engineers, who dogfood while evangelizing the product and writing its technical documentation. Ambiguity or questions are handled by conversations with the engineers that built it.
> its a request for feedback I don't know helps me or not
Yes I'm aware that readers aren't incentivized to respond which explains why it's rare to get higher than 5% response rate. This situation is a microcosm for documentation's overall problem: we can't find incentives for people to voluntarily and consistently confirm the value we provide and we don't have any other means to prove the causality.
Yep, high traffic to a dev doc web page is ambiguous. Is it because it's really good? Is it because it's bad and people keep coming back trying to understand it? Or is the documentation fine but the API being documented is just hard to use?
And when you do this, DO NOT serve up the feedback form/popup from some advertising domain, otherwise developers with ad lockers (many, if not most) won't even see it.
It's getting less simple for new APIs/features but at least Apple's docs have straightforward hierarchy, even with two separate languages. Duplicate APIs usually get deprecated, like the old ALAssets photo library API.
Try building an app in .NET. There are dozens of different breadcrumbs you can follow on the MS docs for varying versions of .NET, Windows, and frameworks with radically different feature parity and UI systems. Virtually everything you google when building a .NET app has to suffixed with a bunch of identifying information for which libraries and versions you are targeting.
Open source has a serious advantage in this regard because communities tend to congregate around project and documentation styles that are consistent with similar projects, so you already have an intuition for how to navigate a new repo. I find React Native documentation especially easy to parse, although sometimes missing features or examples.
OSs have it tough because their docs aren't tailored specifically to each framework and domain space. But maybe they should be. I think if engineers felt more like they owned their product's documentation, layout, and structure like at smaller companies, they'd be more inclined to make it just right. The SwiftUI specific tutorials are great.
https://developer.apple.com/documentation/assetslibrary
But it's also just as easy to get stranded with missing features or features that aren't on both Android and iOS. I did a bunch of geolocation and mapping a while back and I had to write my own support for things like heatmaps. This was eventually merged into the react native maps library, but it is something that can happen if you're doing anything slightly exotic.
A “north star” to lots of designers and engineers from interaction design all the way down to the systems level.
Excellent documentation was part of it. Long game. Best practices. The whole “crafting” DNA seems to have been lost somewhere along the journey.
I think it’s also a function of market driven angst and hence not saying “no” often enough anymore.
I read an ancedote from an aspiring SWE that after he saw the Apple product he couldn't afford, he knew he needed it.
People aren't buying because quality reasons, they buy because of various psychology tricks their marketing department is responsible for.
It creates a system where developers are dragged along to support 100% of users.
This is about “Apple losing the functional high-ground” (which they clearly had at one point) in terms of design, architecture and general “DX”.
All in comparison to its own previous high quality.
In terms of quality of products they still are best in their respective class IMHO. Security, usability and durability are still great/good enough. This has nothing to do with marketing.
Marketing is necessary to bring up as Security and durability claims have been debunked enough times. Perception isn't reality, but similar to Tesla and Jeep owners they have high satisfaction despite objectively poor qualities.
You only need to try giving your grandparents a iphone to realize usability claims are greatly exaggerated.
yeah, like the keyboard of the laptop I'm writing from...
I mean, look at SwiftUI. Conceptually it's great, but it is also fucking buggy as hell, and I think one of the main reasons is that the developers themselves don't have good documentation available. The best documentation so far I found is this, but it's third-party: https://www.objc.io/books/thinking-in-swiftui/
It is quintessential form over substance - like Apple's fucking 'butterfly' keyboards.
SwiftUI is butterfly keyboards of software - wait until you want to write non-toy code with it, you'll be needing 'hack #235 by content creator #563' to make trivial features possible.
SwiftUI brings concepts from React and Flutter to the Apple ecosystem, which is great. It's especially great for people writing non-trivial software, because we don't want to spend our time on doing trivial stuff.
I've been so lucky to have to learn near a dozen programming languages in the span of less than a decade to write CRUD apps that appear on screens and do the same thing on each platform slightly differently.
I only hope to be more lucky in the decades to come, maybe I'll have to learn two dozen new languages and three dozen new frameworks to write CRUD apps that show up on computer screens.
What I am personally doing in no way negates the fragmentation that is present. SwiftUI is the latest contributor to never-ending CRUD hell and I am merely informing the young and impressionable, that SwiftUI is not your friend - it is your anti-cross-platform, proprietary, closed source devil spawn (being dramatic for fun :)) and if you ever want to start solving real world problems instead of learning the latest framework that does what we did 20 years ago but 5% better this time, you better listen real careful to annoying debby-downers like me, Joe Armstrong (RIP), Rich Hickey etc who got fed up with the corporate matrix and went a different way.
I hear what you are saying. I also find it unfortunate that something simple like UI is so fragmented. But then again, maybe UI is not so simple after all. The current paradigm that SwiftUI copies and evolves is that of React, and it just didn't exist 20 years ago. Funny also that this new paradigm was invented for the web first. While a lot of web stuff is crappy indeed, this is one of those examples where it produced a superior paradigm that is now copied and evolved outside of web as well, for example by SwiftUI, also by Flutter.
That's just how progress looks like.
And let me cue in my rant from a few weeks ago on the same topic: https://news.ycombinator.com/item?id=24947919
SwiftUI is “great” for a calculator demo or a to-do list app. Otherwise it’s just a gimmick, but Apple had gotten anxious about ReactNative and had to make something palatable for the webdevs... Although making SwiftUI mandatory for home screen widget extensions is very concerning, and on the long run they’re probably shooting themselves in the foot by pushing this buggy toy framework...
* Protectionism: The poor documentation defends expert third party developers against competition from new entrants. It ensures a shortage of competent developers and so enhances the revenue of established experts.
* Low commitment: The publisher (Apple) is unwilling to make the functional commitments implied by good documentation. Once the documentation says "this does that" it's harder to change "this" to do something else.
In the distant past, Apple teamed up with the publisher Addison-Wesley to create and publish high quality documentation. They could certainly do so again, with A-W or O'Reilly or whoever.
But they won't do it as long as they have business reasons not to. They have sufficient control over their marketplace to refuse to do this and get away with it.
Why in the world would Apple want to ensure a shortage of competent developers — for apps on Apple's platforms! — or protect third party experts?
Raising barriers to entry for new developers is a cost-cutting measure for them. And fewer apps on the store, even at the margins, is a revenue enhancer for incumbent app developers.
This may or may not be an explicit factor in their decision making. But it surely contributes to their lack of focus on docs: better docs will improve their profitability not at all.
Because taking your existing VoIP application and inserting CallKit behavior breaks in so many mysterious and undocumented ways that I really had to tell a client it wasn't going to happen with his existing application within the allocated budget.
Just to get the fancy Apple call screen!
And of course only FaceTime can take video calls straight into video from the lock screen, so you have to explain after it works why nobody can see each other.
iOS docs were great back in 2011.
From what I've read, Jobs certainly understood the importance of software, but only great software. He didn't want the Apple ecosystem to become loaded up with crapware like on the IBM, or on the Apple ][ for that matter. So, if a small time developer couldn't write and distribute a crude but useful app, so be it. Favored developers probably didn't fare any better with the documentation, but help was a phone call away.
This was the "closed box" philosophy that I don't think has changed much over the years.
The irony was that "crappy but open" attracted more developers than "wonderful but closed." This is why apps such as assemblers for microcontrollers were written for MS-DOS. Essentially, even after the introduction of MS Windows, the ability to write for DOS provided a way to create and share simple apps.
They didn't cover "class libraries". I don't have copies of whatever documentation was provided with MacApp, I do have a Think-C manual that describes their environment.
AKA the windows API/etc documentation, linux man pages, etc.
The vast majority of modern documentation is worthless autogenerated garbage when it exists. It lacks good examples, meaningful overviews and functional diagrams. In many cases its woefully out of date because someone rejiggered an API and didn't bother to even update the inline documentation.
One of the better examples of recent documentation is the core rust docs/books. Even then because the rapid release cycles no one publishes an updated "Learn Rust" book for every release, complete with boxes explaining what has changed since the last release. And god help you if you dig to far into the library ecosystem.
I think this is caused by one single problem. Documentation isn't sexy and no one is paying technical writers to do the grunt work anymore. Opensource is a large part of this problem, but the commercial guys have discovered they can save a few hundred thousand a year by simply not having a documentation team, and it doesn't appear to affect them much. A couple youtube tutorials and they are done.
You can see this in the evolution of software, etc. In the 1970's you got large paper manuals which covered every technical aspect of the machine/software. The users were expected to use their brains. Then in the 1980's it all transitioned to "user documentation" which was more focused on manuals that explain how to use the product, by removing the how it works part. Then in the 1990's it started moving to digital copies on disk, and the product came with a 3-4 page manual explaining how to bootstrap enough to read the rest of the docs. In the 2000's it all moved online and became more "marketing" than users guides. In the 2010's they stopped even that. Now you get a phone/software/computer your lucky to even get a piece of paper that tells you how to turn it on, charge it, or install it. Even ms doesn't publish a complete guide to all the magic swipes and keystrokes that are supported by their new shell.
Lets look at https://docs.microsoft.com/en-us/windows/win32/api/synchapi/...
Function description, supported version information, header-file and library file information, meaningful return code documentation, links to an overview of the system wait behaviors, documentation about what happens in low power situations, links to example code using the function, differences in behavior between differing versions, it goes on and on.
Can you point to something you think is better?
PS: I should point out, I have paper copies of the win32 api from the early 1990's that are falling apart from the use they got.
edit: Holy crap, in an effort to find an online picture of the volume, i noticed that amazon is selling the slightly newer ones for over $800. Looks like I should have taken better care of it.
He was trying to find out whether it's safe to call a particular iOS API function off the main thread. Obviously, the docs didn't say. He googled a bit and found a support forum where someone had asked. An Apple engineer responded: "I don't know, but I'm looking at the code, and there sure are a lot of locks!"
As for SwiftUI (documentation aside) it is very powerful, even with its current API holes, and the benefits are huge. You do have to slightly rethink how you might approach certain things but ultimately SwiftUI produces shorter and cleaner code with no XIBs. (Hint: If you do end up with pages of hacky work-around code, you’re doing it wrong and should stop.) I have no doubt it will be the primary/preferred mechanism in 1-2 years.