The Elephant at WWDC
eclecticlight.co
eclecticlight.co
The reason I think the quality and quantity dropped was the internal schedules barely (or don't) leave enough time for the engineering work so there's very little time available for high level documentation. Internally tons of "documentation" existed as Radar comments or exchanges on internal mailing lists. Maybe a group's wiki had some crystallized documentation or high level architectural descriptions but good luck accessing it from outside that org. My favorite was some discussion about overall design or architecture that got the "let's take this offline" where all the helpful details ended up shared in an in-person meeting.
The internal secrecy and rapid development pace made it really difficult to get good overviews of technologies internally. I really sympathize with outside developers trying to cobble together an understanding of something where the documentation sucks or is missing.
The DocC tooling isn't going to be anymore effective than doxygen or other auto generated documentation without good architectural documentation. A function definition is nice but knowing you need to decombulate a frobnob before snizzlizing or that decombulation can only safely be done on the main thread is often more important. I can read a function signature but I can't necessarily know all the keys that go into some configuration NSDict passed into it.
I hope the situation improves if the DocC tooling lowers the friction for writing documentation. It sucks having to mix a WWDC presentation, sample code, and iffy docs into a semblance of usable architectural documentation.
Explanations of design intent might be the most underrated kind of documentation. There's so little of that nowadays in general, in any technology. Personally, I blame shortened attention spans, the death of programming books, and the rise of Stack Overflow. I'm not familiar with the Apple ecosystem, is it really worse in this regard than others?
I also blame dogmatic misunderstandings that have crystalized around "Agile." Maybe back in the day a some cookbook process specified a lot of useless documentation be created, but many people seem to have thrown the baby out with the bathwater and declared all documentation useless or not worth the effort.
Also some programming books are to blame. IIRC, the book "Clean Code" completely rejects comments because they can get out of sync with the code and therefore be misleading, and "clean code" should be self-documenting. However, all code can ever tell you is what is, it can never tell you why or what was really intended. Also, when you really think about it, method and variable names are comments too, which can get just as out of sync with what's really going on than a comment block.
What it recommends to just delete are comments like
var speed # the speedIt's the easiest to keep in sync. It lives in the code it documents. It's in the same version control repo and the same version of the source building a binary can build the docs. If it ever does get out of sync with the code it's the most straightforward to fix because it's the same process for fixing an issue in the code itself.
Tests are not documentation. They only test a very limited "what" or "how" and give no explanation of "why". If it's closed source software and you're only shipping a binary, the tests do not go with the binaries so they're meaningless to third parties. Sample code isn't much better. Without the organizational pressure to keep it in sync with the code it's demoing and "why" explanations it doesn't provide a lot of useful insight for third parties.
If you didn't attend that WWDC session or pour over all the recordings you've missed that particular key concept. So you're then sort of feeling your way around some new technology and making it work but it's not as efficient or elegant as if you had the whole picture.
Because there's so little documentation time and Apple does not (as a rule) do engineering blogs or similar there's not a lot of of opacity into inner workings or designs. From the outside there's a lot more reading of tea leaves than you see for other platforms.
No blogs is fine, that's just the corporate culture, but no blogs and no good up to date architectural documentation is a huge problem. It leads to cargo-cult understanding or complete misunderstandings by outside developers. Hell, it leads to cargo-cult understanding by internal developers.
I think a great example of this is the difference in docs between OSS Python projects.
Most include the auto generated Sphinx (or whatever) docs, with usually just a README level veneer. I quickly end up needing to wander the code. I swear any OAuth2 client library is fated into falling into this.
The great ones include a “quick start”, overall philosophy/architecture, sections on each sub component, common examples of “advanced usage”, and then the generated API docs (and source code). They let you dig deeper as you learn more, and hit more complicated requirements in your project. Click, requests, Flask, etc. are great examples of this to me.
Sphinx and other tools can be leveraged for all of that. But it does have to be written and maintained.
And not having access to the source (internally or externally) kills me for app dependencies. Sometimes I need to look just to understand the doc or see if I’m making a mistake or there’s a bug. Not trying to get into OSS philosophy, just the practical part for me.
Even the official Python docs can stink in places. The subprocess module replaces X, Y, and Z to be “simpler”, but if you want to know the method args, go read the docs on the thing it “replaces.”
I love “native” apps on my mac, and pay for quite a few. But I’d never try to make one. Even XCode is befuddling to me. It’s not an IDE, it’s an opaque RAD that makes me nostalgic for early 90’s Delphi.
I do recall from my iOS development times that Apple's documentation and articles were really good.
It’s a mess. Case in point: introduced in the new beta: loadSimulatedRequest:
https://developer.apple.com/documentation/webkit/wkwebview/3...
What does it do? Don’t know. I can make a few informed guesses from the name but I’m not sure if it’s maybe a performance measurement tool, or just a way of loading faked data. There is no documentation. To the best of my knowledge it isn’t covered in any talks either.
/*! @abstract Sets the webpage contents from the passed data as if it was the
response to the supplied request. The request is never actually sent to the
supplied URL, though loads of resources defined in the NSData object would
be performed.
@param request The request specifying the base URL and other loading details
to be used while interpreting the supplied data object.
@param response A response that is used to interpret the supplied data object.
@param data The data to use as the contents of the webpage.
@result A new navigation.
*/https://developer.apple.com/documentation/webkit/wkwebview/1...
but I suppose it allows for more customisability. Marking the existing one as deprecated would go a long way to solving the mystery. Assuming that’s even correct! This is where documentation beyond literally only detailing what the API does would be great.
https://developer.apple.com/documentation/swift/string/28948...
That may actually be worse than no documentation because you wasted time looking for what is in essence a mere repeating of the function call and nothing else.
It's nothing more than an autogenerated documentation page for a method that hasn't yet been documented. And it's specifically listed as being recently added so that explains why.
I find pages like this all the time in the Java, Rust, Python etc ecosystems. At least with Objective-C/Swift the method signatures are consistently well named.
When software distribution was tied to hardware mediums, it froze snapshots in time, and the documentation thereof could be snapshotted with it (to varying levels of success). Even needed to be.
But once it all became primarily net based, it meant the software was always fluid, in motion. Imagine the tech writer approaching a developer now days:
"Explain how this works to me"
"Ok, right now, it works like this, but we're working on a revised version for next year..."
"Sigh. Ok, explain that to me too."
"You bet, but make sure and check back with me before you publish, because some things might change yet."
It's an irony, that the original dream of "the web", a distributed documentation system, is rendered ever instantly out dated in the realm of software because of the distribution models it eventually enabled. Unintended side effects I guess.
As a side anecdote, consider man pages for venerable established Unix commands. Now consider the man pages for newer Unix utilities. IME, the newer features are often under documented and require going to code portals to get detailed/up to date answers.
"What does the software do?"
"What do you want it to do? We can add that."
"Well, I want to be able to access my old work in a few years, and maybe use it in another program."
"I pinky promise that that will happen, and we will make that happen, after we get through all our other customer requests."
It's not exactly a new problem that we keep updating software - "bells and whistles" is an old piece of hacker jargon - but there isn't a sense of definite publication now, because there are so many methods of blackboxing in the way, and that's been allowed to take place through the promise of "one more thing" and "surprise and delight" - we only really put up with it through a sense of increasing hype and spectacle. If you have a really firm grasp on what you want the computer to do, you can eliminate just about every application program.
We also explored the idea of perhaps putting the docs as postscript files on an internet server with a ghostscript app and some instructions on how to ftp the files or something. That all seemed so close to right, but not quite feasible.
We weren't even considering the internet for software distribution. It was all an idea to provide our customers the latest and greatest documentation. But the internet was not established enough to let us refer customers there for practical use. And ghostscript was some hokey concept from people in some GNU movement or something and wasn't close to production quality.
Three years later we lived in a completely different world.
It's also possible that it's not just that things are distributed on the net but also that the speed of development as accelerated. Some of the is undoubtedly due to the net (easier access to lots of resources/sample/libraries) as well as easier to collaborate and a ton more people doing it.
Strong disagree on that one. Writing good code is all communication - with the computer, with your colleagues, with your future self who doesn't remember how or why you did something. It's written knowledge transfer. Blocks of code, just like paragraphs of documentation, need to both fit into a whole, and be as accessible as possible on their own to someone jumping straight into them (e.g. someone straight from google, someone jumping in to do a quick bugfix or merge fix). The list goes on and on.
Modern programming languages and frameworks are explicitly designed so that you don't need to see how your code fits into the whole. That's the whole point of building abstractions, because it's too hard to keep all of the details in your head at one time. Writing code is generally concerned with the low-level details, which are hidden from other parts of the system (and that's a good thing). When you ask someone a coding question, that's what you are testing. To the point of the article, yeah maybe there is some correlation between someone who is good at writing code and good at writing API documentation.
The complaint in the article is that the high-level conceptual documentation is lacking. The systems design stuff. The architecture. And while there are certainly people who are good at writing low-level code as well as understanding high-level architecture, that's not always true, as they are very different skillets (and I don't mean this as a slight against anyone, it's probable that most people who are good at one could become good at the other, but in practice, many people's jobs lead them to spend more time on one instead of the other, so that's where they build up skills and experience).
Anyway, the higher-level documentation is a very different style of writing. It needs to read like a book (as opposed to API documentation which is more like a dictionary or encyclopedia). You need to be able to pull information together from lots of places, and it must be presented in a methodical way, where (for example) you can't assume that the reader has knowledge of something before you have presented it.
Modern day software strives to do this, but regularly falls short. To craft the abstraction correctly, you need to understand how it is to be used—this is its “whole”. The person writing the internals of the abstraction who does not understand the whole writes the internals poorly. They create a feature that breaks expectations. They optimize a code path whose unoptimized implementation is relied on for one reason or another. The consumer of the code who does not understand the reasoning for these low level implementations starts relying on sub-behaviors that aren’t actually intended. This is why even the low level folks need to understand the (proximate, at least) whole.
What you’re describing is the lazy programming strategy that is certainly easier but results in dependency stacks that are brittle. It means you can plug a junior developer in anywhere without a mentor, but it also means QA efforts are enormous or breakage frequent. In UIs, it’s how Apple can rewrite applications in a new framework and lose decades of system behaviors because no one fully understood the whole when they replaced the abstraction.
Abstractions are leaky. It is in their nature. Understanding or describing how they are meant to be used makes the leakiness a little more obvious, a little easier to understand. Any given team can choose to be lazy about this of course, and will export the costs to their code’s consumers.
The output of a single individual may lack this context, of course. That is why the best abstractions are often created by teams over time: it takes skill in both typing code and devising and describing architecture to create a good tool in the form of an abstraction. It takes those same skills to achieve continuity over time in maintaining a given framework, application, or other abstraction. Documentation is an assist to the tribal knowledge that helps support this continuity, and a way to export that knowledge to new people, and try to make it outlast the original designers if the abstraction.
Again: Code is always "low-level" (regardless of how much you do or don't know about the rest of the system) just like most API documentation. The complaint of the original article wasn't about API documentation, but about higher-level conceptual documentation being lacking. And just like not all "coders" may be able to design a large and complex system (though they may certainly be able to understand it) they also may be unable to document those high-level conceptual aspects of the system.
GP said a whole, not the whole.
A subsystem, abstraction, or whatever, works as a whole, not as unconnected pieces, and the code needs to reflect the organization and concepts within itself as a meaningful whole.
That reinforces the idea that a programmer might be good at one kind but not another.
Totally agree. When I need to learn a new subject like Core Audio or something I get a book.
https://www.amazon.com/gp/product/B007R3U9W2/ref=ppx_yo_dt_b...
It is mainly geared toward MacOS development but there is a section specifically about iOS for things like Audio Session. You will probably still need to keep the Apple docs open for iOS specific stuff here and there but in general the book does a GREAT job of bridging audio theory, with apple's architectural decisions, with low level implementation details. IMO thats the great strength of books, they tie it all together and this one - for me at least - checked all the boxes.
Who maintains these? Most development teams I've met never bother checking the example code works. 99% of the time, they'll write up a presentation, once, click "record" on the video conferencing software, and everyone says "cool, it's documented". And then, 6 months later, half the presentation is obsolete, and it ends up being even more confusing because as the reader, you have to investigate what has changed since this presentation happened.
I've noticed, if you put some real thought behind maintaining these higher level docs, you don't end up with _tons_ of documentation. And the speed of adoption is rapid. But it takes design, a feedback loop, etc. It's really another kind of deliverable, separate from creating a software product itself.
It's best to have documentation in a variety of communication formats. I cannot learn by watching a video as well as I can by reading, but everyone is different. If the only, or primary, documentation for your product or code is a video, I'm likely to pass on it unless there are no other choices.
Do anything else you want for your audienc3, but for me personally if there is not textual documentation, I will consider your system, software, library or whatever effectively undocumented.
Many people do not stay focused with longer formats in writing. So adopting a variety of media is a good idea, especially for the fuzzier "conceptual" documents, as opposed to reference documentation.
And I say this as someone who prefers books. I've made the mistake of only using writing, and noticed about half of the team just never seemed to grasp the concepts. Example projects with really short videos helped them a lot.
Writing good documentation requires empathy. Writing good code does also. However, it's in general more difficult to empathise with someone who has a fundamentally different background than yourself. Some developers can write code other developers on their team will easily understand, but they're not necessarily able to understand the way less technically inclined individuals (or individuals with a different expertise) think.
Generally speaking, this is why UX is such an important field. Writing good documentation is about understanding the target audience, and being able to understand the user's journey - which may be very different than your own.
If the documentation for the "outside of Apple" audience is not good enough without access to the source code, then developers feel it and the overall result is that Apple suffers as a platform.
And the resources required are tiny. Technical writers are cheaper than developers, and you could hire a top team for $1m a year. Doubling that would still be a rounding error in Apple's revenue stream. Multiplying it by 10 and introducing good management would be enough to make Apple's dev docs world-beating and legendary.
Apple could also run developer classes and camps online and f2f, publish its own books, create a regular stream of developer newsletters and tech updates, run forums that are actually useful, and so on.
The fact that none of this is happening at scale is... unfortunate. WWDC is a small plug in a big hole, and doesn't come close to meeting the community's needs.
Coming from Android, I was used to having high level conceptual guides on the core building blocks of the framework. In the Android docs, I found detailed explanations of Activities, Fragments, Views, and other major components. It was relatively easy for me to get started, and the system was designed to be extensible. Google even published blog posts regularly, which I could use to learn more about design decisions.
When I made the jump to iOS, though, it was difficult to find parallel documentation for what I was looking for. At the time (this was 2015, mind you), I couldn't find anything beyond API documentation for ViewControllers, Views, Core Data, etc. Most of the major documentation existed on third-party sites like NSHipster. Not to mention code signing. I'm pretty sure I'm one of handful developers at my firm who knows the system well enough to explain how it works...and that was after 2 years of working in iOS full-time.
I doubt that Apple will prioritize the developer experience on their platform anytime soon.
Edit: In case anyone wants to see the difference...
- Google's guide on Activities: https://developer.android.com/guide/components/activities/in...
- Apple's guide on View Controllers: https://developer.apple.com/documentation/uikit/view_control...
There are other factors preventing improving it, because documenting a new project is effectively adding more people to the project team (even if they're "just" writers) and they still need to learn it by talking to the developers, who might not have the time, so it's not scalable. Third-party documentation scales by not being able to talk to those people and instead reverse engineering everything, but that would lead to embarrassing incorrectness if it was the first-party approach.
Being able to write is a skill in its own right, but it's one which anyone can acquire with practice, and it's one which many programmers would benefit greatly from. Writing code is only one part of the job, and writing documentation, requirements and design is a big part of the rest, and these parts are just as important. It's often the case that the act of writing down these things identifies inconsistencies and omissions which have not been picked up on during design or code review. And, ultimately, your libraries or application need to be used by other people, and if it isn't properly documented it's going to fall short of expectations since people won't be able to use it as intended.
It becomes most curious with exceptionally talented people who are terrible communicators - they can engage with exotic and difficult pieces of code, but almost everything they write ends up being a trainwreck that nobody dares to use, nobody understands, and is typically riddled with bugs. Code is built to be used, and at the very least, you have to hand it off to other developers, or you're stuck maintaining it yourself. (In several cases like this, I've seen one of these programmers hand something off, and have others basically struggle to use it, and work around that by writing something much more rudimentary to replace it.)
I feel like a programmer needs to understand writing for the same reason a general needs to understand what it's like to be on the front line - even if they're doing very little of it themselves, they need a clear understanding of what needs to be accomplished and what the difficulties will be.
It’s not that a software engineer isn’t capable of writing, but more that it’s not their primary responsibility.
I also anecdotally believe that having people in roles like this who are accountable for documentation, design, etc improve the overall product as they provide another layer of review.
It is valuable for my career to be able to write somewhat well but I am hired and earn my salary in other ways, debugging weird technical things; two days experiments, code reading, and maybe gdb and then one small PR and a short email explaining the issue. Write some nice network server to solve a network issue; implement some feature in a maintainable way. Etc. lot of work and mostly the way of thinking about it is a small piece of that work.
The tech writers made a small book that could be handed and/or emailed to people who then integrated with my API with no further interaction between me and them. It was very helpful.
Comments and internal docs can be handled by the engineers themselves, but turning that into an organized and properly formatted manual in a consistent style and voice for outside consumption is a specialized task that can’t be done piecemeal by the same people writing the code.
I'm an ops guy, not a developer, and willing to hold my hand up and say that I suck at documentation. It's a deficit I recognise and work around: I have often paired up with someone who is better at documentation than I am, but less technically apt or possibly earlier on in their career than I am, because it's easier for me to tie a training piece along with the documentation piece. It's kinda like a win-win.
If I didn't do this, generally nothing I did would be well documented. I can write what I think is decent documentation, but I find it tedious and tend to half-ass it. My bad.
But that's not even the worst of it. The worst of it is that there are technical document writers in my line of work and the documents that they produce are an order of magnitude more useful and thorough than the best of my documentation. Like you could ask me to spend a week writing a document and them to spend a day and I'd be outclassed. It's a world of difference.
I know some guys who are good devs and good technical document writers. I know some who are incredible at one and bad at the other. One human can have two differentiated skills, it's true, but they're not at all intrinsically tied.
A good coder does not a good technical document writer make.
And for documentation to truly excel in needs to go far beyond “I transliterated the code into English” or even “here’s all the ways this API can be called” and far into the “here’s how to do what you want and here’s what you didn’t know you wanted.”
That last part is often the most missing - documentation that educates and informs on all the new options not just the new ways of doing old things - of which Inside Macintosh is a great example.
The skills to write good documentation approach something more resembling an English major than a programmer.
It's hard to write good documentation without being able to visualize:
- What they know
- What they don't know
- What they're probably trying to accomplish
Some of the best API documentation comes in the form of examples, which doesn't draw much on writing skills.
That said, explaining high-level concepts/theory does require writing skills, but it also requires the skills described above.
Here's a high level overview of GC to give you an idea of how thorough these documents are now:
https://docs.microsoft.com/en-us/dotnet/standard/garbage-col...
After reading through all of those sections, I will have developed a very strong understanding for how GC works in .NET and how I should strategically approach it for certain types of problems. I would also have clear, specific code examples to follow as appropriate.
The best thing for me is that when I click the "Edit" button on Microsoft's documentation, it takes me directly to the latest markdown source file on GitHub and I can immediately submit a PR for corrections or enhancements. Good luck doing something even remotely like this with Apple.
The linked article is a bit off base, I think, because clearly Apple's documentation problem isn't a tool issue. It's a philosophy of documentation. I like going to the documentation for a critical system API class and finding all of the members, examples for each, and then "related" things. Philosophically Apple seems to have decided that people really want a tiny subset of members to have primary documentation, and then a weird collection of orthogonal things mixed in as equal interest so you can't tell what you're looking at. It really is quite terrible.
Like, yes, the pages that exist are usually very well written and detailed. But jesus christ, their links even just between MSDN pages are constantly broken, if you find an article older than 12 months you can be 100% certain nothing on the page will work when clicked on. It's like there is a wealth of knowledge there, but whoever is in charge of maintaining MSDN makes a point of redesiging the entire website every year and breaking literally every link in the process.
Sony's PS4/PS5 docs also suck and are a giant pain in the ass to get to because they make you allow-list only specific IP addresses (a nightmare during the pandemic), but at least they are all in one place.
And yes, PS4/PS5 documentation is....lacking. It's all in one place and at least easily searchable but most functions have descriptions 2 sentences long and you have to look in the samples for the actual knowledge of how to call something.
I actually went from working at a first party studio inside Microsoft to an indie company, so luckily I have my network to fall back on. Now I just need to work out how to do the same for Sony and Nintendo...
a) crawl your own documentation and find dead links.
b) monitor 404 errors and track down the source (via referer headers, etc.).
c) ask the user on the 404 page what they were hoping for or provide a search menu, record it, and have someone manually review.
d) add a redirect management engine, so you can redirect links that you can't/won't ever fix.Thanks for the tip.
I didn't mean to imply it was trivial, but the concept of crawling your own documentation is quite sound and should just be part of good document maintenance.
There are some plenty good crawlers already. I'm guessing one of them has a 404 report that could hopefully be used to find dead links.
But the tools constantly send you to links that don't work or provide no useful information. It's a very weird disconnect. I never trust the "click here to open documentation page".
Just the other day I was trying to look up a behavior specific to an older version of Windows and the content was completely replaced with content only relevant to Windows 10 (and there was no real parity here to what I needed). I had to go to archive.org to find the information I was looking for from that page.
When I can actually find the docs I need, they are usually great but all too often just finding that content is frustratingly difficult.
No, they've had lot's of documentation. That's not the same thing. For decades it was very shallow with no examples. You'd get an enum list with a half sentence explanation.
The last couple of years they've really upped their game. With detailed examples, explanations and even source in multiple languages.
To me Qt's documentation was the benchmark, but the latest documentation from Microsoft has really caught up.
This kind of snotty reply is always interesting. I've been a professional developer for 25 years. For most of those years I was deep in the Microsoft platform. C++, Win32 API, DirectX, COM+/DCOM, OLE, automation, C# / .NET.
For decades they've had exhaustive narrative documentation that would give huge backgrounders on everything. Architectural "how it fits" documentation with wonderful diagrams, hierarchies, etc. I could easily find anything and jump to specific APIs. Shitloads of examples. They clearly have had a great documentation focus for a long, long time. Something like the MSDN Library was years before its time.
Let me repeat, probably with way more experience in saying this, that Microsoft has done documentation well for years, and I seldom felt deprived (aside from occasionally when they do a restructure and search engines/links go to obsolete links). It is specifically in contrast to Microsoft's long excellent documentation that I find Apple's to be a sad joke.
There is some bizarre tendency in here for people to pretend that everything Microsoft does well they've only done well for most recent history, as if this is some sort of odd proselytizing and naysayers should realize that everything has changed.
I didn't interpret it as "snotty" (not beyond the norm for this forum, anyway). Could have been worded better, but charitable interpretation is an HN guideline.
> There is some bizarre tendency in here for people to pretend that everything Microsoft does well they've only done well for most recent history, as if this is some sort of odd proselytizing and naysayers should realize that everything has changed.
Or perhaps the parent just disagrees with you on merit and there is no nefarious underlying motive? In my experience at least, Microsoft's ethos and behavior has improved significantly in the last ~decade with respect to openness, developer friendliness, attitude toward open source, product quality, etc. It seems clear to me that there is some broad cultural change at MS and it seems plausible that it could affect documentation quality as well.
Personally, I don't have a dog in this documentation fight, but your comment seems unjustifiably angry.
But a lot of things were already very good to excellent. I mean, one of the things you mentioned was developer friendliness yet the company has forever had industry leading developer relations. They've always had great documentation (there are going to be some developers who will still struggle and fail, but that isn't the fault of the documentation which can only drag them so far). SQL Server has been a great product for literally decades. NT was actually a great OS for the era and vis-a-vis its contemporaries. Microsoft has always been very "open" in fields where they are struggling. And on and on.
They did a lot of great things in the past along with bad things. And right now they're doing great things along with bad things. Every org is a mixed bag.
But they are quite actively rebuilding from the switchover. I still miss CHM.
N.B. The first time I've read Time Management for System Administrators, it was CHM file I just copied onto my free (won in competition) Windows Mobile PDA.
You always have to get a 3rd party book to figure this crap out... if you can find one. And if you're off and on, then you're constantly playing this game every few years.
Frankly the X11 books out of O'Reilly are my standard for "good."
It’s a typical HN Apple Zealot tactic. They simply lie to boost their cult.
Win32 doc has always been good, back into the 90s. Some of the Sharepoint and Lync and when they were starting to open source all the things has been lacking. There was also that stretch where they axed all the QA department... Shudder...
Apple quite frequently left important details and it took me few weeks to understand why the decoding code misbehaved in one particular case. With Microsoft I run into this only once and it was straightforward to fix. Note that in both those cases with Apple and Microsoft StackOverflow and similar sites was not helpful and even harmful retrospectively since that gave wrong direction to dig, but this is another story.
On the other hand Microsoft documentation was more shallower. If one knows roughly what to do, then things are OK. But by just reading one can not learn how to solve problems. Guides were not helpful, as those were at too high level.
Surprisingly with Apple, when they did described API, they gave helpful hints what to do next. Plus API was named more sensibly.
True, Microsoft has always had extensive documentation.
However, during the Ballmer era, there was tremendous version confusion. It was no longer clear which version of software a lot of documentation referred to.
I've noticed a huge clean-up in this regard after Satya took over. I suspect he got some very competent person to take over all the public-facing documentation, to make it more user-friendly.
The result: I am willing to trust Microsoft documentation again.
I remember somewhere between 2006-2009 they did a reorganization / reimplementation of their online documentation which meant that the menu was always far too long to load and sometimes killed the browser I was on. Whatever point it was at was the point when I stopped using MS technologies as I figured the open source was just as well, and if not as well documented, at least trying to read the documentation seemed a lot safer.
It truly seems philosophical. Someone there thinks this is a superior solution.
Not to mention that the Windows help system was better in the early '90s than the Mac's is today. Help on the Mac is a disgrace, which is why a lot of applications have just started delivering a PDF or doing all Web-based doc (which sucks when you're trying to work offline) instead of bothering with it.
They have _tonnes_ of new-user intro stuff and similar. Super impressive at first look, but once you're past that and need to dig into complicated things it's all undocumented.
Even most of the auto-generated pages in their Python SDK function lists are just "Header -> empty space where content should be -> footer". And nothing else.
... and lets not get started on the docs for Microsoft Graph. :/
Firstly the documentation for the various SDK is often an issue, because it's often behind the latest release of the SDK.
For .NET libraries especially, there is just so much churn that they obviously struggle to keep the docs updated.
And then secondly, as you say, there just aren't enough examples beyond the most trivial.
(Note: I haven't touched PHP since 20 years or so, so not sure if it's still the case).
But I did like the comments idea
Haven't worked with much MS things besides that but it left a very good impression.
The "orderby" query parameter is documented as "orderby query parameter". It is secretly an enum; the values are things like "time_asc" and "time_desc".
Later, take the response. "lastUpdateTime" is documented as "Last update time". It's documented as a string, which while technically correct (at the JSON level, yes, it is a string, ish), is wrong. It's an RFC 3339 datetime — I think¹ — but it's also wrong because it is — bizarrely — optional. I actually don't know what sets it, and I have no examples of it being set and the docs don't help.
I could also refer one to their documentation about the various performance characteristics of various Azure VM types. Some VM types just aren't listed, so if you're curious about those, good luck, I guess? Run them yourself?
We've also hit things like various tri-bools. IIRC, whether you're on a paid SKU for AKS is a weird tribool of sorts. The field has two values, represented by three values: "Free" (meaning free), "Paid" (meaning paid) and the field simply not being present at all, meaning the same as "Free". Not only is the chosen representation terrible, that it is this way is undocumented.
¹I don't have a counter example yet, at least…
It gets a bit uglier once you cross into WINAPI, COM, etc., but Apple's is still not even close to being a match.
I feel like .NET documentation has significantly improved. It wasn't that long ago when I had no idea how to find the documentation from the MSDN home page and had to rely on search engines, but outside I agree. Microsoft's documentation gets a bit rough. Most recently, I found the NDIS documentation unbearable, with broken links and links to 5.x versions. Additionally, I was trying to find the documentation on OLE, and google kept leading me to MFC specific stuff, which was not what I was looking for.
https://docs.microsoft.com/en-us/windows/win32/api/wininet/n...
(Hint: what does the function return? Countless pages of function references got their return types set to "void" for some inexplicable reason. If that isn't incompetence or malice, I don't know what.)
The best thing for me is that when I click the "Edit" button on Microsoft's documentation, it takes me directly to the latest markdown source file on GitHub and I can immediately submit a PR for corrections or enhancements.
I actually asked about that error before on their GitHub, but they basically said they'll handle each case as it gets raised. No, I'm not going to fix docs that you broke. It looks like MS basically got rid of all their actual documentation writers and are now trying to rely free labour from the "community".
gRPC is one of those projects that I'm not sure if Google really wants uptake or if it's just a dump as a means to open source other things they want uptake in (GCP client libraries, tensorflow, etc). The documentation is awful.
We had better than that 10+ years ago: actual wikis. We've regressed quite a bit. Even developer.mozilla.org has gone backwards. Had devmo not been a wiki, I'd have never poured so much effort into the JavaScript docs between 2006–2008.
Aside from joking, now internet is no longer peaceful enough to keep publicly editable wiki.
Microsoft under the new management has really turned around and become a “good” tech company (relative to google and Facebook).
Does anyone have any recommendations for resources to learn or is it simply reading through documentation akin to that Microsoft link and others like Stripe?
And Microsoft documentation has been excellent for decades. Even pre-Internet with MSJ and Microsoft press.
Literally 99% of anything I search for in Microsoft documentation these days lands me in a page where the only additional English text is the function definition with spaces added between the words! Entire APIs are 100% undocumented, at least in this sense. Security-related APIs are totally undocumented. APIs critical to disaster recovery are totally undocumented. I could go on and on.
It wasn't always like this! The C# standard library documented used to be fantastic, with multiple pages of text for pretty much every function. Now? It's hot garbage.
Let me give you an example. Not a contrived example of some obscure API that nobody cares about, but a "flagship" feature of dotnet core that was heavily advertised recently as a significant step forward in its capabilities:
System.IO.Pipelines
// Gets the MemoryPool<T> to use when allocating memory.
public System.Buffers.MemoryPool<byte> Pool { get; }
I am enlightened! I understand now. Before that documentation page, I could not figure out that a getter called "Pool" returning "MemoryPool" returns a memory pool to use for memory allocation. But wow, that documentation really cleared things up!
I know I'm being more than a bit snarky, but it's deserved.
Microsoft's work is not GNU. It's not truly open source. It's not made by volunteers. MSFT is not a charity. In fact, their products in general are very expensive. I pay through the nose for this! I pay through Windows licensing. I pay through Azure hosting costs. I pay through Office 365.
What do I get for this money? Function names with spaces added.
> The best thing for me is that when I click the "Edit" button on Microsoft's documentation, it takes me directly to the latest markdown source file on GitHub and I can immediately submit a PR for corrections or enhancements.
That is the worst thing about Microsoft documentation. They've realised that they no longer need to allocate any budget at all to technical writers, because people like you will happily volunteer your own time to fix something you're already paying for with your actual cash money.
Stop.
If you're going to volunteer your time, do it for a charity. Write a Wikipedia article or contribute to Linux. Don't use your precious time on this Earth to help the world's second biggest company for no compensation whatsoever!
They’re a small but mighty team that’s constantly overwhelmed, so I look forward to seeing how DocC can help them out and produce more docs.
I think this is an incredibly common situation. Personally speaking, I find that to be an excuse. If a woefully understaffed team of tech writers got the budget for 15 new tech writers, that usually wouldn't solve the problem.
The main issue is developers who don't believe documentation is highly important.
The "we generate documentation, so we're covered" is exactly the attitude I'd describe as highly unproductive. Of course that's great, but auto-generated docs are a small part of what should be your overall documentation suite. It shouldn't become the developers' excuse for not spending more time on documentation.
Tech writers will very rarely write docs from zero. I wouldn't even be surprised if the tech writers at Apple had no access to the source code, in which case they can't possibly write the docs from zero.
> They’re a small but mighty team that’s constantly overwhelmed
Perhaps Apple needs to spend some money and effort there, but that sounds like a management problem.
From what I can see and what others have mentioned, DocC is an Apple-blessed version of existing community tools like Jazzy. Apple could have been using that already, and indeed the engineers could have been using any number of docs-in-comments systems to generate basic API docs that could have been then forwarded to the docs team.
But even if they didn't have that, it is still up to the engineers to get that information to the docs team somehow, and still up to the docs team to ensure that new APIs and frameworks are documented. Full stop. Someone, probably a PM somewhere, should have the responsibility to make sure those things happen in tandem. For example, new features and new frameworks could go in a issue tracking system, those issues have descriptions from engineers of at least the barebones basics, the docs team has access to those issues, and separate documentation issues are created and linked to those issues. And lack of basic documentation should arguably be treated as a release blocker. I am sure there are a lot of engineers in the audience raising their hands in protest at that, but when you're talking about an API or an SDK, the documentation is essentially your user interface. You don't need to have the equivalent of the multi-volume Inside Macintosh documentation ready to go on shipping day, but you need to have a basic Jazzy/Javadoc-style reference and an overview doc on day one.
I don't doubt Apple's documentation team is "small but mighty," but there seems to be something fundamentally broken in Apple's process. If DocC helps, that's great, but at best it's just a start.
One example for me is ReplayKit... yes I don't know too much about Audio/Video but the little documentation there is it feels deliberately obfuscated and lacking. Better API level docs would help but it absolutely needs more high level guides and examples. One WWDC talk linked on a page is not enough.
I once spent days trying to update old AV player code get close captions working with Vimeo streams on iOS, half that time was just trying to understand how captions worked in AV streams at all.
Every time something like AV gets a new set of APIs, Apple should update a detailed overview that explains we used to do things this way, then added these Kits to make it easier to do these things and you should only use them for these specific things now, because we have now have added these new Kits to address these new needs, or make this other thing easier, etc.
And I’m sick of watch videos. Give me a high level overview of the why and how of the managers, and in it link directly to detailed documentation pages, sample source code and pertinent WWDC videos so I don’t have to use my Google fu to figure out those links myself.
This is what I'm personally tired of. WWDC might actually be interesting if they focused on the developer...
For example R developers usually document functions, data, etc using Roxygen in-line comments and they use vignettes for tutorials and the like. An additional advantage of R is that it checks that the documented function arguments line up with the code function arguments (at least by name -- it has no way to judge whether what the developer makes sense, of course).
I'm not saying that this is not useful, because I think it is, very, useful. It's just that this seem more like catching up than leading, at least in the broad strokes.
It looks pretty much like what folks have been doing in Swift for a very long time. DocC is just Apple’s own version of Jazzy / SwiftDoc / appledoc. There’s no catchup here, it’s just Apple making an “official” version of something that already exists.
w/r/t the article, I feel like engineers should write documentation, but so should product managers and customer service reps. I feel like both explicit (written by principals) and emergent documentation (forums) make sense.
It's an admittedly big lift, but if no one can figure out how to use your library/package/software, in the long run you'll be beat by folks who make it easier to do so.
0: https://www.mooreds.com/wordpress/archives/6
1: https://www.oreilly.com/library/view/the-new-kingmakers/9781...
I don't have time to track down a bunch of old WWDC videos and hope that they approach something like usable minimum developer documentation when combined. I start that process about once a year and every time throw my hands up in resignation. Life is too short.
Documentation was part of the Framework, and accessible through Project Builder.
You could also package a Bookshelf and search from a Service.
Apple is a hardware company, despite the money made from the app store. They don't lack for outside developers fighting bad documentation to make apps.
Poor documentation is not surprising at all; it's to be expected as there is little incentive to change.
In my last company before I jumped, I architected and implemented our full data infrastructure along with one other engineer. Which means I was responsible for high level conceptual documentation and low level documentation all the same and while I've written documentation before and for years I'm not formally trained in it so it was all still basically winging it. Since then I've actually taken a few short courses on writing better technical documentation since I felt it was a weak spot and having tools to assist in making that easier would have been great.
Documentation is hard and has been neglected but man does it have major underlying costs to getting it wrong.
Everything from on boarding being slow to misunderstandings that cause expensive bugs and everything in between. The root cause is developers have a hard time understanding complex systems and we as an industry are really hit and miss on writing the documentation that would make that understanding easier.
At my place we have an eternal struggle in “level”. We have some very high over docs, then ADR for specific decisions. At the lowest level we have the api documentation which we find most people don’t read. And then we have some tutorials. Every time I read our documentation it feels very inadequate of conveying all our knowledge and intentions.
https://developers.google.com/tech-writing
Google has two short courses about 6 hours total or so that seemed a good consistent basis for me as an engineer writing documentation.
I'm not sure if it's going to answer your question on what types of documentation you will need though and how to make it feel less inadequate just how you as an individual can write better documentation.
- The Craft of Scientific Writing, Michael Alley
- The Craft of Editing, Michael Alley
- A Guide to Writing as an Engineer, David Beer and David McMurrey
- On Writing Well, William Zinsser
There's also a plethora of stuff on the web, as you might imagine, too much to go into it all, but McMurrey has a website https://www.prismnet.com/~hcexres/textbook/acctoc.html
Isn’t this just a misread of what DocC adds?
I watched the “Meet DocC documentation in XCode” wwdc session and the very first thing they talked about is how it complies Articles and Tutorials as well as reference documentation and how they can cross reference.
This was part of the code challenge at the company I'm currently working for. Checking how the candidate's solution was documented is a well defined part of the review process.
The one the author focuses on that's missing is the explanatory type. The sort that's discursive and provides a broader understanding of the whys and hows of the code.
Two other kinds of useful documentation that would complete the package are tutorials, of the sort aimed at programmers just starting out with the material, and how-to-guides, for programmers that have a general understanding of the material but could use examples and steps to accomplish a specific goal with the system.
The thinking for a long time was that computer software was compute-limited, that all applications were as intensive as video games, audio / video editing, and 3D rendering. In reality, people may pay for innovative interfaces and data formats when they organize their work in a new way. Software could be used in an "offensive" way to take entire industries as interlocking roles within organizations. Each of these roles, save manual labor and janitorial work, benefits from education, and the nature of that education is to develop certain patterns of thought & behavior.
Software could be designed with the educational background of the user in mind. I'm speaking mostly of enterprise software here, but it could be applied to CAD shops, publishing, anyone who has an education and uses a computer. I'm not talking about Mechanical Turk here.
The idea is to take education philosophy as the common software for all education computer-enhanced roles and design software for educated people that exposes stuff like
- the ideal way to learn the structure of the software data model
- text and point-and-click data input and output
- data processing languageI think quality documentation can be written within the markdown that explains how higher levels concepts work. I see this in Rust all the time.
Spent many years as senior dev for a custom Android ROM, yet Levin's book still introduced me to multiple other Android internals I had not yet looked into. Would happily pay 200-300 for his next Android book. Probably not the best books for a total beginner, but if you're already skilled and looking for the next level I would highly recommend.
My only real complaint is that JL seems to do a lot of the marketing/date-setting himself, and it shows. It can be really confusing to keep current on what book he is working on next, what topics will/will not be covered, how to even pay for the book can be a bit complicated (send paypal to this email), etc. It is fantastic that he adjusts and expands book contents as the market/technology changes (e.g. always chasing to get the newest stuff covered in the newest book), but the current end result is a stream of "update" messages on his website that are hard to follow. Would be wonderful if he had someone help him with that "public-facing" side and try to keep things organized/consistent/obvious and hide a bit of "how the sausage is made"
I think it will make documentation better, not because DocC is the perfect solution, but because it re-emphasises the importance of documentation because its new. It also gives developers at Apple a standard tool, was there such a thing before?.
That said: some folks didn't really get the memo, because there are important details that are sometimes included in non-doxygen comments in Apple's headers and thus aren't reproduced into Apple's generated/published docs.
In particular, the headers (sometimes) include annotations for specific types included in CF containers for return values.
Yes, Jazzy, SwiftDoc, and appledoc already do this, plus whatever in-house tool that already existed at Apple before this (they have clearly been using something like this for the past ~15 years).
Also, DocC is integrated into Xcode, all the others tools could not be.
Been nearly a year back with Apple hardware now. What a change! The tools are very flash, but nothing quite works. The easy bits are done, feels like 95% of perfect. The documentation is good if you just need to be reminded, but if you need anything to help in the early part of the learning curve, it is third party blogs, (that really feel to me like astro turf, but they do exist).
The licensing! Why do I keep getting blocked from using hardware bought and paid for! My colleagues and I have spent, literally, days trying to get me into some sort of licensing scheme - truly Kafkaesque.
It feels a lot like Linux in 1997 - mostly works and brimming with potential. But whilst Linux was on its way up in 1997, Apple feels like it is on its way down.
And they are busy fighting to keep quasi legal monopolies instead of fixing the last few problems in their tools and writing proper documentation. What a shame
What are they doing, are they from apple or not? You're hopeless, aside from some comments here and there from random members of the community.
To this day, I have no idea what 'powerd' is, for instance.
You're in luck, there's an extremely helpful and well written man page on exactly that subject. I will quote in its entirety:
"NAME
powerd -- Daemon that manages Energy Preferences.
powerd is a launchd managed daemon.
powerd is a launchd managed daemon."> There's no place to find out what they are.
Google worked fine for me. YMMV.
In the first place, and this is an unpopular opinion, people have simply accepted “Apple's documentation sucks” as truth but the documentation problem hasn’t been properly defined or framed yet. I personally think that the view, view controller, Core Data, animation, networking, and Bluetooth, and concurrency guides are excellent. What parts of the Apple SDKs exactly are people having a problem with? If it’s just the latest APIs like SwiftUI, does that make the whole platform deserving of an unqualified negative perception? I don’t think so, and it doesn’t help that in my experience, the people who complain the most about Apple’s documentation are the ones who go to a Medium article first and before consulting Apple’s own documentation.
FWIW, when I’m involved in hiring, I absolutely consider this a major factor.
Edit: Why is this downvoted? Do people really think the documentation got worse over the past few years?
I was introduced to this app, which I think is a great help (I referenced it above): https://swiftui-lab.com/companion/
---
there are lots of third-party sites that do a great competition with apple for documentation, especially for swift/swiftui and i get the feeling that apple is maybe conflicted... they want to solve thier problem of documentationm but
1. there are lots of great (albiet scattered) resources on the internet already
2. things change radically year after year (uikit → swiftui, x64 → arm, etc); its hard to maintain a "tome" at apples pace and scale
3. apple is all about effeciency; stopping to write a book when you could be coding or innovating doesnt seem worth it
.... its a difficult situation and would probably cost a lot of money and resources, and logistically, seems like it would slow up development quite a bit (even if someone else wrote the books, you still have to coordinate with the devs)...
The manual for that machine was a masterpiece ... written for users. The 'revolution' ... obfuscating the OS internals, limiting access to the anointed ... was a tragedy. 'Killing Big Brother' my ass.
(It took me a lot of digging - in those pre-web days - to find out what magic numbers to poke, and where to poke, to turn the Mac serial port into a MIDI port.)
Anyway, I expected the 'elephant' to be the array of monopoly-busting legislation floating around the Congress right now. Popcorn ready.
However, I think there was a mismatch of expectations, since the Apple ][ was documented down to the last bit, including the schematics and ROM source code (excluding the Applesoft BASIC developed by Microsoft).
The creators of the Mac wanted to force developers to adhere to the abstractions Apple provided with the OS and to discourage developers from using low-level tricks. This enabled Apple to evolve the Mac much further than the Apple ][ series. The last model of the Apple ][ series, the //gs, had to provide a lot of hardware to enable backwards compatibility with software written from 1977 on.
In contrast, the Mac survived a relatively pain-free transition to the PowerPC in the '90s, which was one of the first wide-spread uses of binary translation in commercial systems (later used for the transition of OS X to intel and now to Arm) - even significant parts of the kernel were still written in 68k assembler on PPC systems.
Of course, there were some significant problems to overcome in the 68k era. One well-known example is that developers (even Apple's developers themselves) abused the most significant 8 bits of addresses to store data. The original 68000 had 32 bit address registers but only a 24 bit external address bus, so the 8 MSBs were ignored by hardware. This was no longer true on the 68020 and later CPUs and caused lots of problems...
Talking about the state of documentation of macOS, even the old NeXT documentation was better and more in-depth - though there was no detailed information on the hardware, which causes problems for the developers of the Previous emulator today. Of course, the NeXT systems were much less complex than it is today, even though you already had to cope with coprocessors such as the Motorola 56001 DSP and the i860 on the Dimension color graphics card (which unfortunately could not be programmed directly)...
Apple then reorganized and rewrote the entire documentation along functional lines, producing separate, smaller, volumes for e.g. Memory, File Management, etc. That New Inside Macintosh series was, in my opinion, the highest quality documentation Apple ever produced.
The heyday was an app that had digitized all the documentation and iirc the code examples were in C. It had hyperlinks between pages. Quite nice pre web reference material.
Their code examples were also helpful, but things like low level double buffered sound recording or high performance animation was left as an exercise to the reader.
There’s a difference between having/understanding an idea and being able to express it in different modes/mediums of communication (in this case, to computers vs to humans). I’m not saying that one can’t learn to be better at a form of communication, but I recognize they are different abilities.
> First, it concentrates on documenting calls within an API by individual function. For a developer who already understands how that sub-system in macOS works, that’s essential. But trying to grok major topics like Attributed Text simply isn’t possible by referring to individual functions within the API. You first need to get your head around how sub-systems are designed and function, the conceptual information which Apple was once so good at providing. Good conceptual documentation is structured and written quite differently from that for classes and functions with an API, as Apple well knows.
It's pretty par for the course, for generated documentation (headerdoc kind of thing). Much of my own documentation is done the same way. I agree. It isn't actually that good for systemic understanding (I use big fat READMEs for that). However, you can do things like use MARK commands and extension blocks to organize the docs. Jazzy, in particular, is good for this. The new Apple doc generator will probably also be good for it.
But Apple's documentation has definitely gone into the skip, and I am glad to see it being addressed. It has reached the level of brand damage; which is usually where they start paying attention.
That said, I completely understand the challenges of keeping documentation current. If we aren't careful, documentation can become a concrete galosh[0].
[0] https://littlegreenviper.com/miscellany/concrete-galoshes/
> In common with almost every other initiative of its kind, this approach assumes that the best people to document macOS are its engineers. Those engineers are often selected at interview by posing them a coding challenge, but have you ever heard of candidates for a software engineering post being selected by or for their ability to document their code?
I once took an iOS class with a woman who wrote a lot of the graphics subsystem documentation for Apple. She was damn impressive (had a Ph.D, but wasn't actually an engineer -she was a writer). Apple hires good people. Unfortunately, I suspect that she may well have retired, by now.
I wrote this comment[1] as a story about an Apple interview that I did, several years ago. It was quite disappointing to encounter their attitude.
[1] https://news.ycombinator.com/item?id=21377358
I've written about my own experience and practice, in regards to documentation[2].
[2] https://littlegreenviper.com/miscellany/leaving-a-legacy/