From my perspective, I was in SWE at Apple for over a decade, their documentation started going downhill as iOS development ramped up. By the time they got to the yearly release cycle for macOS and iOS documentation was an afterthought. Most was generated with doxygen from inline docstrings.
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.
This speaks to me. I’m not deeply involved in the iOS development world but I do a lot of webview-adjacent stuff so I keep a close eye on the WKWebView documentation.
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.
Sometimes you have to look in the headers. I don't know why it doesn't get parsed into the docs. Here's the documentation for loadSimulatedRequest:
/*! @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.
*/That’s very useful information that would be very useful i the docs! Thank you. I’m a little confused as to how it differs from the existing method for loading data:
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.
As I read it, the simulated response call doesn’t actually hit the URL, it just sets up the object like it’s going to then loads the data you supplied. Not sure when that’s useful since I’m not an iOS programmer.
More likely for offline caching of web content. But unit tests too!
My latest one was the documentation for slicing up strings. All the example code for string.prefix() string.suffix() string.subscript() has code examples using arrays.
https://developer.apple.com/documentation/swift/string/28948...
Those are automatically inherited docs (from Collection?), I think Xcode will actually tells you this but for some reason the website isn't.
Wow, I think that's my new go to example for bad documentation.
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.
Not sure why.
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.
New APIs introduced in betas often don’t have documentation until later. When working with beta APIs, read the header.
Isn't the real time most software documentation started going down hill was as the internet became the primary way of distributing and updating software?
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.
Depends on the version of Unix. OpenBSD considers documentation to be a first class feature of the operating system, and new functionality isn't considered ready for merging and release until the documentation is complete and high quality.
It speaks to the contradictory nature of software development as it's currently practiced, I think.
"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.
Most line-of-business software has always been more service than product, and I think we're right to embrace that. If you shrinkwrapped an accountant and sold them as they were, 5 years later they wouldn't be much good for anything. The computer is a bicycle rather than a taxi, it needs active involvement rather than passive use.
I worked on a project in the early 90s to figure out a way to distribute updated docs along with software updates. At the time, the software updates were shipped on CD, etc. We could ship the docs in WordPerfect AND Word formats. But that wasn't very palatable. We talked with WordPerfect about this portable document format thing they were working on (Envoy?). And we talked to Adobe about some sort of similar thing they had in mind. We could ship the document reader for Mac and Windows on the CD with the docs.
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.
I think you're right. I also think there's often an attitude of "break things and move fast". Take a look at three.js, they break stuff every 3-4 releases which makes all the tutorials on the net out of date. They explicitly state they don't care one wit about backward compatibility.
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.
> That’s not why they code, nor are the skills of writing good documentation even vaguely similar to those for writing good code.
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.
No.
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.
No.
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.
Yes, of course, when working on a piece of code (a low-level task), one should know where it sits within the bigger system. One needs to know all kinds of things about what lives both upstream and downstream, as well as some high-level architecture of the system as a whole. But the implication above (which I disagreed with) was that "good coding skills" (and thus a filter during hiring) implied "good documentation skills" does not follow from any of that.
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.
> you don't need to see how your code fits into the whole.
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.
> GP said a whole, not the whole.
That reinforces the idea that a programmer might be good at one kind but not another.
> Anyway, the higher-level documentation is a very different style of writing. It needs to read like a book
Totally agree. When I need to learn a new subject like Core Audio or something I get a book.
A bit off topic but do you have any recommendations for learning Core Audio? Last time I was reading old blog posts and header files to do what I needed.
I used this book and I found it to be excellent.
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.
I've found that the higher-level docs often don't even need to be writing per se. I'd stick things like the 3-5 minute overview video, 30-60 minute presentations, and code examples in this type of category.
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.
> don't even need to be writing per se
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.
Extraordinarily strongly disagree. Documentation should be first, best, and most thorough in written form. It is easily searchable, easily transferred, easily scanned for relevant sections.
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.
I didn't say documentation shouldn't be written; writing is just one of many media types.
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.
You can't rely on documentation to be correct because, like comments, it can't be tested or automatically updated. It's only going to be reliable if the system under it never changes.
+1 Nicely explained.
Very eloquently said, couldn’t agree more.
I believe it depends who the target audience is for the documentation.
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.
Apple's issue is that unless the code is open source, the documentation is the only thing available to the "outside of Apple" audience.
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.
Apple's issue is it doesn't seem to care. I'm going to speculate that improving the developer experience has a low status on the management hierarchy. So even if some people do care they're clearly not being given the resources to do anything about it.
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.
I came to the same realization that Apple doesn't seem to care when I started learning how to build apps on iOS.
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...
Everyone is pretty expensive when they have to live in Silicon Valley - even if not, anyone who interacts with engineers becomes nearly as expensive due to cost disease.
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.
A good coder does not a good technical document writer make.
I disagree. If a programmer cannot articulate their thoughts and ideas clearly, and cannot effectively communicate with others through writing, I would question whether they fully understand the concepts themselves, and whether they are actually a good programmer.
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.
I completely agree. Of the various coders I've worked with over my career, I've noticed an astounding correlation between quality-of-writing and quality of code.
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.
That’s a fair point, but good technical writing is a skill in of itself. Just like having dedicated UX SMEs on a team improves a product, technical writers do the same, especially for complex systems.
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.
I sort of think this except I had a job for several years where we had really good technical writers who would sit with various developer and produce far more accessible writing than I ever have.
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.
Good technical documentation needs dedicated technical writers.
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 don't know why this is downvoted -- it's true. They are two very very different skillsets.
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.
I haven't downvoted any comment in this thread, but I think the parent post was a low-effort oneliner that didn't touch on the arguments made by the comment it responded to, and as such doesn't meaningfully add the conversation (even if it were correct).
You seem to have the writing chops to be a great documentation writer. What is holding you back?
They can coincide in the same person - perhaps Donald Knuth’s form of literate code would be an example - but they’re independent skill sets.
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.
Disagree. The difference between professional technical documentation and something a “good coder” whipped up to explain some code is astounding.
The skills to write good documentation approach something more resembling an English major than a programmer.
I think it's more about being able to see things from the audience's perspective.
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.
Conversely, I have noticed that Microsoft has been kicking some serious ass in the documentation arena lately. If you haven't taken a look at their stuff in a while, you would probably be shocked.
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.
Microsoft has had superb documentation for decades. They put a lot of emphasis on it and the results show.
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.
I'm a games developer working on some AAA xbox productions and I don't think I agree. My #1 impression with Microsoft documentation is that you run into a message "error occurred, click here to open documentation page", you click on it, only to be redirected to a 404 page or simply to MSDN's main website.
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.
Agreed, the Xbox documentation is hot garbage. They expect you to flip flop between the .chm file shipped with the XDK and online, but like you say the links are almost always broken. On the flip side though the private Xbox dev forums are awesome, I find them more useful than the docs.
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.
Haha, yes, direct emails for folks in xbox is very useful, the xfest advice is very solid.
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...
Right. And this would be so easy to fix too.
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.Sarcastic? I can't tell.
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.
I agree with both of you -- Microsoft documentation is generally excellent and extremely detailed and often more than just what you'd get from automatically generating it from code comments.
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".
Half right....
The link rot in MS documentation pages is simply maddening. If it’s not a 404, it’s completely different content that is only relevant to v.latest.
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.
I've seen this. Also the search on the MSDN website is really bad. For some reason it never gets a reasonable result. I use google with site:docs.microsoft.com
> Microsoft has had superb documentation for decades
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.
"No, they've had lot's of documentation. That's not the same thing. "
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.
It isn't that it's nefarious but rather that people who adopted Microsoft late rationalize that the company has a maligned history (some deserved, some not) by declaring that everything is different now. This appears in conversation after conversation where some current Microsoft enthusiast declares that everything was crap, but now it's wonderful.
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.
The last sentence is a real gem. Zero trolling / Real question: What do you miss about CHM? My guess: It's a single package you can easily share and doesn't break once deployed (like a live website). :)
I don't agree with this at all. I spent a solid decade doing predominantly Windows development and I haven't felt the need to buy a book on any Microsoft topic since, like - "learn Visual Basic 5". While they probably had a good stretch of years from like after VS2008 until maybe after VS2015 where the documentation was clearly not a focus, I've never had any trouble learning first-and-foremost from the documentation and have often used MSDN as a good example of not needing to already understand the entire topic to benefit from first-party documentation on that topic.
> This kind of snotty reply is always interesting
It’s a typical HN Apple Zealot tactic. They simply lie to boost their cult.
Qt5 documentation quality has steadily slid down hill. Any new modules they add you essentially have to peruse the source to understand what/how/why it works.
I had a coworker critical of my position while working with Qt when I complained about poor documentation, saying that if I needed to know how something worked, I should just read the source.
That documentation exists at all has been enough to put MSDN at the top for the past couple decades.
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...
I year ago I worked on media decoding code both on Mac and Windows. Documentation for media API sucked on both platforms, but it sucked in different ways.
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.
Embarrassingly, it's been said that Xamarin's iOS documentation is better than Apple's own.
Just my 0.02:
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.
>Microsoft has had superb documentation for decades. They put a lot of emphasis on it and the results show.
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.
Do you really think that's a "philosophy" and not just thoughtless careless underinvestment?
What’s the real difference? It’s the same with good testing. Engineers are expected to operate on timelines and meet deadlines that are often not generated by someone who values good testing and thorough documentation. If Apple wanted good documentation they would have to be comfortable with something that was going to take one week now taking two weeks and they’d probably need to include willingness and ability to document as something they select for when hiring. Or they’d have to spin up documentation teams that work alongside feature engineers, or something. In almost every environment I’m been in, people balk when you force them to confront the reality that good quality things take time and effort. So I don't think it’s just a careless “whoops we forgot to tell the engineers to document” type of scenario. I think it is fundamental to the fabric of the company and those that operate it.
I mean, generating a list of classes and their members, hierarchies and relationships, with basic annotations, is the easiest, most mechanically automated solution possible. Apple's bizarre documentation seems like it would take significantly more work.
It truly seems philosophical. Someone there thinks this is a superior solution.
Amen. I learned enough to start off in C++ from a thin white book from Microsoft about the language. Really excellent.
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.
Conversely, when looking through the Azure documentation last week for much of their Python SDK libraries... it's a joke.
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. :/
I'm a heavy user of Azure, and I have 2 general issues with their docs.
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.
Strangely, the best documentation I've seen so far has been PHP. The only reason: because developers could comment right below the documentation. It's like having StackOverflow right there, in the documentation page.
(Note: I haven't touched PHP since 20 years or so, so not sure if it's still the case).
It still is the case, and the documentation itself has improved greatly over time. PHP is one of the few programming languages that I feel can be used using only the official documentation (with the comments, of course)
Especially the warnings like this ISO date function is not actually ISO-compatible :D
But I did like the comments idea
When I had the opportunity to do something with a Hololens (1st Gen) I was a bit hesitant as the subject matter seemed very difficult and I come from a very different background but when I went through the documentation, tutorials and played around with the SDK I was shocked how simple the SDK and how clear the documentation was.
Haven't worked with much MS things besides that but it left a very good impression.
Huh, I have a different impression. Take this doc, that I was staring at the other day: https://docs.microsoft.com/en-us/rest/api/containerregistry/... ; it is for listing manifests in an ACR repo.
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…
.NET documentation is incredible, not just for the language but also the APIs. It's such a joy to work with and even complex concepts seem to be explained very thoroughly.
It gets a bit uglier once you cross into WINAPI, COM, etc., but Apple's is still not even close to being a match.
> 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.
Some of the older stuff seems to be getting worse. I was searching for information on Active Scripting and it appeared that documents I had used in the past had disappeared. I know nobody is implementing this from scratch but old code needs to be maintained.
Microsoft used to be great at documentation. Then the MSDN->docs.microsoft.com "migration" (what for?) destroyed a lot of old links, and mysteriously introduced errors that weren't there before, like this page:
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".
Yeah, I've noticed this too. Most of the time when you look up something gRPC related, the first links are for some of Microsoft's gRPC documentation!
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.
Idoubt google care if you use grpc for its own sake, unless adopting it for its own sake helps you migrate your important tech to google-preferred versions.
> 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
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.
It's better because we can earn GitHub Internet Point® by editing, isn't it?
Aside from joking, now internet is no longer peaceful enough to keep publicly editable wiki.
I despise Microsoft's products for the most part, but I can't lie: their documentation kicks ass. The C++ documentation is some of the nicest around.
Azure Cloud Patterns is an amazing set of system design documentation. It's not even about Azure, it's just "here's how to design good systems".
One of my favorite bundles of docs to peruse through from time to time. I go in with a specific question and end up going down the rabbit hole of learning a ton of other interesting design patterns instead
Even back in 2019 I was suggesting everybody to read API development design patterns from the Microsoft documentation. It was clean, neutral (not .net focused) and easy to understand.
Microsoft under the new management has really turned around and become a “good” tech company (relative to google and Facebook).
The “Patterns and Practices” stuff on MS’ site was mostly written in the mid-2000s (when SOAP was a thing). A lot of other content came from MSDN Magazine contributing authors, but that’s discontinued now - I’m curious what drives their whitepapers now.
I am currently a year away from graduating and we haven't touched documentation once - simply commenting lines of code during DS&A.
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?
Apple documentation has been awful for decades. There’s so much history and insider knowledge you need to write good desktop MacOS applications.
And Microsoft documentation has been excellent for decades. Even pre-Internet with MSJ and Microsoft press.
Yeah documentation looks fine and all for the LinkedIn API, until you have to deal with failures because of outdated validations or missing explanations.
Are you kidding? Seriously, is this a joke?
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!
This post (while not wrong that the docs lack in a lot of areas) is written with apparent ignorance of how documentation is generated and published at Apple. Right now creating the code and docs are mostly decoupled. Having worked in the department where the docs are made, a tool like DocC is going to let the engineers who work on the code provide better docs to the Devpubs department so the authors there can stop writing things engineers should be writing (since they know it better) and get back to writing the higher level conceptual stuff that requires skill with technical communication that engineers may lack.
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.
> They’re a small but mighty team that’s constantly overwhelmed
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.
If giving Apple developers tools that automatically generate useful API reference documents frees up the devpubs team to generate the other kinds of documents necessary, I'm all for it. If there's nothing but the API documents, DocC won't really address the issues.
> 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.
While I haven't worked at Apple, I've worked in technical documentation at other places (and still am) and worked with engineers, and I can't help but push back a bit on your implicit assertion that better tooling for engineers is going to help Apple make better documentation. Having coding and docs be so decoupled that you're not able to make good documentation is not a tooling problem -- it's an internal communication 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.
Many teams at Apple are small but mighty and constantly overwhelmed. It speaks to the priorities of management to engender the existence of these situations. Or the sclerosis of the company culture.
The way Apple talks about new developer features/systems seem like ads for very exclusive clubs sometimes. "If you are already doing this, you can do it here now and we show you some teases, talk to us if you want to know more".
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.
New Kits are always tacked on, there are few overviews to tell you how an entire area works.
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.
> 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...
I just watched https://developer.apple.com/videos/play/wwdc2021/10166/ to learn about docC, and it looks pretty much like what folks have been doing in other languages for a long time.
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 other languages for a long time.
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.
Apple's comment system has existed for much longer than Swift.
Also: Xcode has been able to parse and display the Markdown documentation comments in Swift code for years. It's really nice! Doesn't mean DocC isn't worthwhile, but at least the PSOTU and Meet DocC presentation seemed to not only ignore outside prior art, but Xcode's existing capabilities too.
I have loved documentation for a long long time[0]. In my mind, as the developer continues to drive technology decisions[1], documentation in all its forms will continue to be a differentiator on par with functionality. Developers are learning all the time because their job is changing regularly, and good/excellent documentation is a competitive advantage.
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...
Incidentally, if you are looking for a mental model around tech documentation, I haven't found a better one than this: https://diataxis.fr/ which discusses tutorials, how-to guides, technical reference and explanation.
I always thought part of the reason node took off so quickly is that the intro docs all had a five line complete code example that was an http server. And when I wrote APIs for customers, I felt I could not do a good job in the API design unless I write an example that used the API, and then I had good sample code to share. I find all three things: conceptual framework “how to think about this API”, example code (with important error handling paths, just just postman collection), and thorough documentation on all the technical details are all important. Tho obviously the latter is done automatically now usually. But it is important to get out things like “I will return 429s and your code must have a good exponential back off/retry policies” to developers at the beginning.
I remember the documentation being pretty good up to and including OS X Tiger - back when Apple was still fighting for marketshare. I haven't tried to write anything for their platforms since then, specifically because the documentation is so poor.
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.
I wonder NeXT was better or bad for documentation.
Pretty good.
Documentation was part of the Framework, and accessible through Project Builder.
You could also package a Bookshelf and search from a Service.
Generally you find good or great documentation where selling the product depends on it.
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.
I think the reality is regardless of what we want, that at most companies the people who write docs are the people who write code. That doesn't mean it's the best way but it does make it the way we have to deal with a majority of time. That's why building tools to help engineers be better documenters from high level through to the low level is I think in the interest of everyone.
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.
Can you please share the lessons learned in the courses about writing documentation or perhaps recommend some courses/materials?
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.
I think it may just be easier to share where I got any of my lessons from.
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.
Can you recommend a book or course for improving ones ability to write good technical documentation?
Not the parent poster but I can recommend some books
- 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
> First, it concentrates on documenting calls within an API by individual function.
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.
>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?
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.
What's happening here is that Apple is only producing, weakly, reference materials. There need to be at least three other kinds of documentation.
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.
I've actually wondered if a True Hipster (tm) ever thought of starting a company to develop software for vintage Apple hardware emulated by one of the many open source choices available. The thinking here is that such software affords a higher degree of reliability since the platform is totally dead.
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 do want to give a shout-out to this tool[0]. The "official" SwifUI docs leave something to be desired, so a developer wrote an awesome doc tool. I found out about this tool from an instructor at a class I took.
The official SwiftUI tutorials are absolutely amazing though. But I agree about SwiftUI-labs and the app, they are fantastic resources if you want to go deeper.
One of the people who presented DocC used to lead both the rustdoc and docs.rs teams. You can see Ferris, the Rust mascot, on their desk.
I think quality documentation can be written within the markdown that explains how higher levels concepts work. I see this in Rust all the time.
Off topic: I didn't know the Rust mascot was named Ferris. That's a lovely play on words.
I thought Ferris was named after ferrous oxide, which is the old name for Fe(II) oxide. But chemically, rust consists of Fe(III) oxide, or ferric oxide. So perhaps a more appropriate name would be Ferrick?
A little artistic license is better than foolish pedantry.
Passion comment: I'll second that most of Jonathan Levin’s books are outstanding, some of my favorite technical guides.
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"
Just tried to order the Levin books macOS/iOS books (wasn't even aware of them), but they don't ship to the UK ... Must be security restricted ...
WOuld not be surprised - he's reported piracy issues in past. FYI I've ordered all books by emailing directly to an email on the website. He replies with "send paypal to xx if you want digital only, send xxx if you want me to mail you a hardcopy". clunky relative to an amazon order but it gets the job done
Oh, very cool, didn't know that digital only was an option!
this article is saying how Apple DocC (the new documentation compiler revealed at WWDC 2021 this week) is not going to solve the problems Apple (and their developers) face. It has interesting examples.
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?.
The general apple documentation for functions, etc appears to be pretty much a customized doxygen. One can see this by reading the header files for some of their frameworks and noting the doxygen comments there match up with their web-published documentation exactly.
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.
> It also gives developers at Apple a standard tool, was there such a thing before?.
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).
Aren't all the ones you mentioned all third party, so I would expect they won't be used at all internally. That makes me wonder if Apple uses open source much internally.
Also, DocC is integrated into Xcode, all the others tools could not be.
You could run Doxygen on the header files in /Library/Developer and it would give you something decent that didn't strip the doc comments.
I learnt to programme on a Mac Plus using Pascal (Lightspeed? I cannot remember the brand). Inside Macintosh is still, after thirty years, in a box some place. I will never throw it out. Well thumbed, and very useful.
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
Something I really loathe about OS X, and it has been becoming worse with time, is the amount of "processes" or whatever that suddenly take 100% CPU. There's no place to find out what they are.
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.
> 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."Haha, amazing.
Besides the man page, the places to look are "spindump -stdout" and "log stream".
And you couldn't be bothered to do a cursory search?
> There's no place to find out what they are.
Google worked fine for me. YMMV.
Could you please, then, point me to a creditable source regarding what 'powerd' is?
You can use the 'man' command in Terminal to pull up the man page (see: https://en.wikipedia.org/wiki/Man_page) for 'powerd' (that is, by typing 'man powerd'). By doing so, you'll see that it is a "launchd managed daemon" that "manages Energy Preferences."
No, I couldn't be bothered either.
It’s odd that no one has pointed out yet that the article is conflating macOS user documentation with developer documentation.
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.
> have you ever heard of candidates for a software engineering post being selected by or for their ability to document their code?
FWIW, when I’m involved in hiring, I absolutely consider this a major factor.
There's usually a vague "communication skills" aspect of interviewing, but it's not formalized. I'd be interested in hearing how you evaluate candidates for this.
Part of my team’s interview process is a small do-it-at-your-leisure at-home exercise in a repo we provide. Beyond the “solution”, we also get to see tests, documentation comments, commit messages, etc.
What I've witnessed a couple of times is that there can be tremendous amounts and great documentation if the feature/framework can be broadly marketed. If it's on a marketing pamphlet it gets a lot of attention but as soon as it becomes standard or a bit less desirable the quality and extent of the docs are the first thing to go it seems. Sometimes "better docs" is the marketed feature but as all marketing campaigns go, they seldom leave a lasting impact.
I've been playing around with Swift/SwiftUI recently and while the documentation is still unclear in some areas, it is significantly better than the documentation for their Objective-C APIs was a few years ago when I was trying to make an iPhone app.
Edit: Why is this downvoted? Do people really think the documentation got worse over the past few years?
I am not a fan of the SwiftUI docs, but I have yet to do a full-fat SwiftUI app.
I was introduced to this app, which I think is a great help (I referenced it above): https://swiftui-lab.com/companion/
It seems like they've improved them quite a bit from what they used to be, but that app is great! Thanks for the recommendation.
The manpage situation was already horrible in early versions of OS X (around 10.2), which gave us lots of trouble getting Ethernet to work on a switch without autonegotiation (ifconfig options listed in the manpage didn't work, since the Xserve G4 driver didn't support it) and OpenLDAP for authenticating Linux clients...
my interpretation of this situation is, if (whether by intention or not) it can be outsourced, it will be outsourced
---
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)...
"Inside Macintosh" superb? I was puzzled and then disgusted when I saw that in stores, and realized the difference between Macs and the Apple II.
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.
"nor are the skills of writing good documentation even vaguely similar to those for writing good code". I disagree. Vehemently.
Wasn’t the original Inside Macintosh supposedly a nightmare? Did it improve dramatically over the lifetime of (classic) MacOS?
The original MacOS was vastly more complex than contemporary 8-bit operating systems. I think Apple produced very useful documentation with Inside Macintosh - the Human Interface Guidelines that came a bit later are still useful today.
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)...
The original Inside Macintosh was quite decent. The main problem, I think, was that it was hard to understand just pieces of it; if you read it cover to cover it was pretty good. But by the time Inside Macintosh VI rolled around with its 1750 pages to cover the System 7 additions, that approach had run its course.
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.
It was also assembly and pascal for the longest time, even when most folks had switched over to C.
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.
I thought it was very clear, and I kept it on my bookshelf long after it had become irrelevant. I only chucked it to make space for other things on the shelf.
Writing code and writing documentation are completely linked, if you can’t do one, you probably can’t do the other.
Isn’t this a little like saying that because I can’t express myself well in Finnish, I probably can’t express myself well in English? Or maybe more like saying that writing about a topic and speaking about it are completely linked?
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.
Is this a problem in Windows? My dev work doesn't come near OS-specific issues, so I don't know.
Does `docc` works only for Swift? Could we use it for other programming languages? eg. Java
Basically every other programming language has already had something like this for a long time, e.g., Javadoc and Doxygen. Is there a particular reason you'd rather use DocC than these well-established alternatives?
I'd love to use it for Objective-C too. I work on a mixed language SDK and right now use Jazzy which is fine but I think there's a realistic chance DocC will lead to Jazzy being abandoned sooner than we can get rid of all the Objective-C.
Javadoc seems very restrictive in terms of user interface, search etc., It is also not interactive. Hence, looking for something better.
DISCLAIMER: I used to own the entire Inside Macintosh series (when it was only two or three books), so I know how far the great have fallen.
> 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/
Asset Management Companies In UAE https://endemajfunds.com
> 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.
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?
> 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.
To be fair to “Clean Code”, although it’s stance is clearly towards less (superfluous) comments, it recommends using doc strings to document intent.
What it recommends to just delete are comments like
I completely agree. I never understood the argument of docs getting out of sync. If an organization prioritizes documentation then the comments are just as likely to stay in sync as the variables.
And presumably you can track down when the inline docs diverged from the implementation, and who did it.
Documentation isn't automatically checked. Tests and sample code are a better alternative, since you can configure things to give you a build error if they ever get outdated.
Apple's architectural/design intent documentation is sort of hit or miss. The biggest issue (IMHO) with overall architecture documentation is too often it doesn't make it into written documentation. The key insights are sometimes the middle ten minutes of a WWDC keynote or presentation.
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.
I see. Engineering blogs do fill some of that role in Microsoft’s stacks. This is not completely ideal either. Blog posts are frozen in time, and newer articles tend to only describe the deltas. So to get a current understanding, you also have to puzzle together various bits and pieces. But at the very least, blogs are easily searchable.
While blog posts aren't ideal they're (like you point out) better than nothing. But blogging goes completely against the grain of how Apple operates internally. The WebKit blog is a singular notable exception because that's a highly visible Open Source project. Even the free-form Q&A portions of WWDC sessions are rarely as frank as they should be in terms of usability.
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 don’t think any tool fixes that, as you alluded to.
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.
The documentation of Delphi was pretty good. We received Delphi (1.0) on a Friday. I took the manuals home for the weekend to study. I started developing on Monday. On Wednesday we had an application with about 10 screens with access to a database and a working interface to a smartcard reader. Though Delphi certainly had its flaws, I still miss it for developing GUI programs.
And I don't get it. A company like Apple could hire a small army of technical documentation writers who could go to town on it.
I do recall from my iOS development times that Apple's documentation and articles were really good.
It is not Apple that has these problems. In the last years I have been doing some Android development and the documentation is pretty horrible.