On Apple's Piss-Poor Documentation (caseyliss.com) 123
Casey Liss: For the last year or two, I've come to realize that the number one thing that makes it harder for me to do my job is documentation. Or, more specifically, the utter dearth of documentation that Apple provides for its platforms. As a developer, Apple provides us a series of tools -- APIs -- that allow us to make apps on iOS, iPadOS, macOS, and tvOS. In many cases, it's fairly straightforward to figure out how to use these APIs. There's only so many ways you can use a screwdriver, and similarly, in many cases there's only one obvious way to use an API. However, as users rightly demand more complicated and fancy apps, the APIs often need to get more fancy and complicated as well. Suddenly you look up and, instead of only using screwdrivers and hammers, you're using power tools and complicated saws, and everything is much more fiddly than it once was. With real tools, you'd expect to receive an owner's manual, which explains how to use the tool you've just purchased. A rough analogy exists for APIs, insofar as most platform vendors will provide documentation. This is basically the "owner's manual" for that API.
Apple's documentation has, for years, been pretty bad. Over the last couple years, it has gone from bad to awful to despicable to embarrassing. All too often, I go to research how to do something new, and use an API I'm not familiar with, only to be stymied by those three dreaded words:
No overview available.
This is Apple's way of saying "Fuck you, figure it out." No overview available is so bad that a popular Apple resource -- itself something that probably shouldn't have to exist -- used it as its namesake for a single-serving site to highlight how bad Apple's documentation is. The march of progress doesn't help, either. As my friend Adam Swinden pointed out to me on Twitter, as old APIs get deprecated, often times the new ones can't be bothered to include documentation. Check out the difference between this API and the one that replaces it. No overview available. Fuck you, figure it out.
Apple's documentation has, for years, been pretty bad. Over the last couple years, it has gone from bad to awful to despicable to embarrassing. All too often, I go to research how to do something new, and use an API I'm not familiar with, only to be stymied by those three dreaded words:
No overview available.
This is Apple's way of saying "Fuck you, figure it out." No overview available is so bad that a popular Apple resource -- itself something that probably shouldn't have to exist -- used it as its namesake for a single-serving site to highlight how bad Apple's documentation is. The march of progress doesn't help, either. As my friend Adam Swinden pointed out to me on Twitter, as old APIs get deprecated, often times the new ones can't be bothered to include documentation. Check out the difference between this API and the one that replaces it. No overview available. Fuck you, figure it out.
You must be new here... (Score:5, Informative)
Documentation is something to be hunted far more often than it is found 'in the package', pretty much with every API. Apple may be worse than Microsoft, but I've rarely seen good examples of documented systems. While in development systems change so much that documentation is usually out of date if written before the release, or not urgent enough for the sprint if after.
Re:You must be new here... (Score:5, Interesting)
Good technical writers are rare. Technical writers that want to write programming documentation are really rare. Companies that want to pay technical writers what they are worth are nonexistent.
Re:You must be new here... (Score:4, Informative)
I don't remember where I saw it, it was probably either here or on a random tweet, but apparently Apple literally fired all their technical writers when they moved over to the new documentation system, and that's why the current documentation system is so sparse.
So, uh, yeah.
Re:You must be new here... (Score:5, Insightful)
There ain't shit for USERS.
. I mean there's likely a ton of gestures and things apps will do, but you don't know about them until you accidentally stumble upon them and then have to figure out what it is doing to find a search term to then figure how to get out of it.
More than a couple times, I've had extra windows split up on my iPad and I had no idea what I'd done to cause it...and then had to look up how to close the damned thing and get it back to normal.
Sure, its a feature, but man..why don't they give a general manual out for every iOS update that has listings and examples of the features.
I have no fucking idea what all is in there that actually might be useful to me.
God help me when my 75+ year old parents stumble upon something like this and have to try to describe to me on the phone what they're seeing and try to figure how to help them out.
Re: You must be new here... (Score:2)
That's why 3D touch is such a joke
Re: (Score:2)
I had screaming matches with the designer at my old job over these. He fucking loved them, but could never give me an adequate explaination as to how a user is supposed to know they are there.
Its basic UIX , discoverability. If you wont provide a fucking manual (and lets face it, app-store apps and websites generally dont get to do that) then figure out SOME method to signal to the user that the length of the press and the hardness of the press means different things.
Because they'll never guess it and be st
Re: You must be new here... (Score:2)
You know it supports 3D touch the same way you know it supports long press. The only difference is it's easier to both test and to accidentally discover.
Re: (Score:3)
The manual for using iOS devices is preinstalled in the iBook eBook reader.
Re: You must be new here... (Score:2)
"Apple literally fired all their technical writers when they moved over to the new documentation system, and that's why the current documentation system is so sparse"
Good way to kill morale, and tell workers to not put in any real effort because they are worth so little. So yes, expect crap.
Re: (Score:2)
I'd believe it. Back in the early to mid '00s, the API documentation was really good, but then it turned to rubbish. The manuals for their computers and software, which were great in the early '90s, had already turned to rubbish before that.
Re:You must be new here... (Score:5, Insightful)
Technical writers are part of the problem, because they rarely understand what they are writing about, introducing vague ambiguities or omitting key info altogether.
The best documentation is written by the people who wrote the code. When that's not done, it's because either the programmers or the management is lazy. ...And usually they are.
Technical "writers" should be relegated to the position of technical editors, cleaning up poor quality writing by actual technical people.
Re: (Score:3)
"vague ambiguities" often means "getting to the actual point of what the fuck the code does" as opposed to egowanking over meaningless details.
no, the best API documentation is not (usually) written by the ones who wrote the code. the only case where the ones writing the code will necessarily write the best documentation is when it's a very deep technical domain with critical failure modes, like bare-metal systems programming for something nuclear, or foundational crypto. APIs like those of Apple and Google
Re: (Score:1)
That is plainly wrong! Every recent language of today has a feature to write API-Documentation inside the source code like doc-strings in Python or Javadoc comments for Java.
It is absolutely unacceptable behaviour of the developer, who doesn't document the class/method/procedure ... this way as is absolutely unacceptable behaviour of the responsible management, who doesn't enforce decent documentation, especially API-Documentation.
Technical writes and API-Doc are the enemy (Score:2)
Many companies have Quality standards about API docs. Every procedure, every parameter, excepetions thrown etc. Must be documented. Maybe an example of uses as well.
The result is lots of meaningless words that just describe the method signature.
" The Fiddle(Foo) procedure is used to Fiddle Foos. Foo is the foo being fiddled. Fiddle(new Foo()) is an example of usage."
The odd bits of real doc are lost in the mess.
I have often wanted to a system that could automatically generate the meaningless documentati
Re: You must be new here... (Score:3)
Maybe we just need better programming languages. I've been learning rust and the built in means of handling failures is brilliant - if what you're doing has failure conditions, then the output is either a Result or Option, which means you know about it before compile time and without needing to look through documents.
Re: (Score:1)
Usually both ....
Programmers don't write good docs (Score:5, Insightful)
Good tech writers know how to write, and they know how people who use APIs use them and how they interact with API documentation. Which is to say:
"Show me what I need to know to get up an running and do it fast because my boss is on my ass, and make sure I have access to reference info for the more obscure stuff. Use as few words as possible and give me some plain, simple sample code in a popular language".
Re: (Score:3)
It's not that "programmers or the management is lazy", it is far more a case of upper management not seeing any reason to spend resources on documentation. Most of the time, programs continue to tick away without intervention. When they need upgrading/modifying, there's a good chance one of the original devs is still around, and can do what is needed is short order, without needing documentation. And, in the case where a new dev is handed the work, they *can* figure it out ... given enough time.
As for ou
Re: You must be new here... (Score:2)
"When that's not done, it's because either the programmers or the management is lazy"
The programmers are too busy solving problems and getting X, Y, Z to work together by deadline to stop and write a book about what they wrote. And of course, there's burnout.
Management...um...err...keep telling the programmers to "work harder"?
Re: (Score:2)
No one is using dead lines anymore in software engineering unless he is a complete moron.
Switch job if you are "forced to meet deadlines".
Re:You must be new here... (Score:5, Informative)
As a technical writer, I resemble that remark. I realize there's a large range of quality among technical writers, but the good ones couple a solid understanding of engineering with the skills to write good documentation for an audience other than themselves.
The people who wrote the code usually write dreadful documentation: it'll be incomplete because the coder will assume things to be known or self-evident that aren't, it's not their core business so they haven't developed writing skills, they'd rather be coding so they rush the job, etc. By the time a technical writer has finished finding and filling the holes in the docs left by the developers, he could write the documentation from scratch.
In the course of my documentation projects, I talk to engineers and coders a lot. Every time I do that, I find they skip important bits of information. They've been immersed in the project for so long that they find it difficult to impossible to look at the product with the eyes of an outsider.
Re: (Score:2)
If you understand enough to write useful docs, you are an Engineer that also writes, not the other way around.
I do not think that you can gain that knowledge unless you have also built real things.
Architects are the people that should write the docs. There design specs become the final docs after a bit of tweaking.
The difference between docs written by a somebody vs a nobody are chalk and cheese.
Re: You must be new here... (Score:2)
You sound like somebody we need on staff! As the only native English speaker in our engineering and product teams, Iâ(TM)m often asked to help review documentation in out SDKs. Most of my colleagues communicate very effectively in English as a second (or third or fourth!) language, but formal written English intelligible by our customers is a whole new level. It's very time consuming for me to help: it can often take more than 15 minutes to rephrase just one sentence once you've factored in figuring
Re: (Score:2)
You just have to think THE APPLE WAY (Score:5, Informative)
Having made my living as a technical editor for many years, I have strong feelings about your comment. Not sure I would mod it funny or insightful even if I ever had a mod point to give.
However I think the problem with Apple is different. Actually goes back to the evolution of the "Think different" meme. Did you share my impression that the original idea was about the freedom to think differently from other people? Especially from the IBM droids? But what they really meant, or at least the way it has evolved, is that Apple insists you think in the "proper" Apple way.
As it applies to this story, if you think the "right" way then you don't need much API documentation because you "naturally" want to do it the way Apple wants you to. However I can't really say much along these lines because I haven't done any serious development on Apple platforms for many years. Decades.
However speaking as a customer of Apple products, I can say that the "Apple way thinking" is overwhelming and I often find it quite offensive. Just went another round yesterday. Not sure if this anecdote is sufficiently close to the topic, but...
So I bought this beautiful MacBook Pro a few years back. Poked and probed and tried to find useful purposes for it. I don't like to fight with my tools, so I try to find the way the tools want to be used. After a lot of poking ant probing the main thing that seemed to be useful was the dictation. Used it for a while, and then Apple "upgraded" the software and suddenly the dictation was MUCH less useful. I don't mind that so much as the impossibility of finding any path to Apple to suggest that there might be another way to do things. The NEW Apple way had been decided, and too bad for me if the old way was more effective.
Maybe I have a grudge? I'm not saying I was swindled, but I certainly feel like that MacBook Pro was one of the worst investments I've made in a machine. After a while the battery swelled up, but Apple was kind enough to fix it on warranty. Oh wait. Then the new battery swelled up. Now Apple wants me to consider upgrading to a new MacBook Pro? I rather think not. Might be the Apple way, but it isn't mine.
New business proposal: A business to eliminate batteries that can swell. As it would apply to my MacBook Pro, I would probably lose the portability, but could still use it as a dictation tool. (Oh, wait.) However the big market opportunity is for old-but-still-good-enough smartphones. I've had at least three and probably more of them die only because the non-replaceable batteries started swelling. If the phone is still good enough for some purpose, why not remove the non-replaceable battery and run it with an (easily replaced) external battery pack? (But I confess that I am a bit of a weirdo... Did you know that you can tether many Android phones through their USB cable and thus connect to the WiFi network the smartphone is using? I've used it for printing and a couple of quite old computers, and I think there was one time when I was bridging two LANs.)
Re: You just have to think THE APPLE WAY (Score:3)
The apple way is to hide things that make them look bad. That's why they deleted the information on B&W G3 data corruption from the knowledge base. If you really, really need to know something about Apple, the one thing you can be sure of is that you can't find out from Apple.
Re: (Score:2)
I concur. My own primary evidence is from the public discussion "forums" under Apple's control. My belief is that it includes not just evidence of things that are bad, but even suppression of expressions of emotion that are negative towards Apple. At the same time I think they incentivize idolators, so to speak.
Re:You just have to think THE APPLE WAY (Score:4, Informative)
In re: Battery swelled up
If you refer to the battery expanding physically then I predict (I hate Apple products so I don't know that much about them) that your MacBook Pro has a LiPo battery and you leave it plugged in all the time. LiPo's don't like being charged all the time, they out gass and swell up (I've destroyed 3 phones that way). My solution is to put the charger on a timer so it's off overnight. That should give the LiPo a chance to recover without swelling up.
Re: (Score:2)
I have heard a LOT of versions of things that the user can do to reduce battery swelling. Evidence is mixed. But if anyone knows the truth, then it's Apple's experts.
You might have a good idea. Or maybe you're actually damaging the long-term life of your battery with more charging cycles? Based on some of the evidence I've seen, I'm especially concerned about small increments of charging and discharging.
But the USER SHOULD NOT HAVE TO BE AN EXPERT at fighting battery swelling. Apple has the data and for sma
Re: (Score:2)
My current theory--but I am NOT an expert in fighting battery swelling--is that the device should normally charge itself only partially, perhaps to 80%. If the device sees that it's connected to the power almost all the time, then it should stay down at a safe level. In a scenario like the one you describe, the device should figure out if you travel on a regular basis and bring itself to full charge shortly before your departure time. Maybe peek at your calendar for hints? And of course with an option to trigger a full charge when you know better than the Apple Way.
This is the real world. If Apple were to do this then slashdot and a dozen other sites would be flooded by people complaining that their phone doesn't ever charge to 100%, is stealing their calendar data, and is a horrible horrible product that they regret buying. And maybe 5 of those posters would be iPhone users.
Re: (Score:2)
Actually, based on my discussion with an Apple support person yesterday, it seems that they do have this as an option that you can enable. He says it's available on newer iPhones and MacBook Pros. We didn't discuss other devices. It's called "Optimized Battery Charging".
Knowing what to look for, I found this: https://support.apple.com/en-u... [apple.com] but it isn't possible on my older MacBook Pro. Apparently some hardware is required.
I was actually trying to find a reason to consider upgrading my old MacBook Pro. Th
Re: (Score:2)
Thanks for the additional evidence. Just confirming, but this is not a removable battery?
Re: (Score:2)
Ah, yes... blame the user. Sounds to me that the charger is garbage or the company doesn't care about long-term battery life.
Re: (Score:2)
Apple laptops can be left plugged in all the time. When the battery is full it stops charging and the laptop will be run directly off the power supply. When battery level drops to 95%, charging will restart.
Re: (Score:2)
However I think the problem with Apple is different. Actually goes back to the evolution of the "Think different" meme. Did you share my impression that the original idea was about the freedom to think differently from other people? Especially from the IBM droids? But what they really meant, or at least the way it has evolved, is that Apple insists you think in the "proper" Apple way.
As it applies to this story, if you think the "right" way then you don't need much API documentation because you "naturally" want to do it the way Apple wants you to.
I completely agree with this. My experience is that if you want to X, and want to do X in exactly the way Apple wants you to, then you can do X with a click. You don't even need to deal with the nuisance of a pop-up window telling you that X was done.
But if you instead want to do Y, which isn't much different from X, then things go sideways quickly. It's not clear how to make that click do Y, and that lack of a pop-up window means you don't know if your click did X, Y, or nothing at all.
I acknowledge that I
Re: (Score:2)
Just the ACK, both for the concurrence and for the extension.
Re: (Score:2)
Did you know that you can tether many Android phones through their USB cable and thus connect to the WiFi network the smartphone is using?
And did you know you can just do the same with an iPhone, too? Most certainly via Bluetooth, and definitely by setting up a local hotspot with you iPhone. Wow, that was so easy.
But it is sad that dictation sucks, never used it, so no idea about it.
Re: (Score:2)
Thanks for the information, but Apple's "Do it OUR way" attitude is why I don't think I will ever own an iPhone to find out.
On the dictation thing, I basically don't like to force tools. A screwdriver is not a chisel. After buying that rather expensive tool, almost surely the most expensive computer I'd bought in a long while, I spent quite a while trying to figure out what it was good for. In particular, I was looking for things that I could do better there than on various other machines. The dictation was
Re: (Score:2)
Re: (Score:2)
Re:You must be new here... (Score:5, Interesting)
Re: (Score:2, Informative)
> Currently trying to get into (generally) 3D programming
Professional game developer and graphics programmer here. I'd recommend learning OpenGL to start as it is MUCH easier. There a million tutorials around. You'll probably want to take a look at these excellent primers:
* Render Hell 2.0 [simonschreibt.de]
* Beginners Guide to Learning 3D Computer Graphics [youtube.com]
* John Carmack's Principles of Lighting and Rendering [youtube.com]
* NeHe Tutorials [gamedev.net]
* Bisqwit's Creating a Doom-style 3D engine in C [youtube.com] (Oldie but goodie. It is an introduction to Spatia [wikipedia.org]
Re: (Score:2)
Re: (Score:2)
Back in the old days. When you got a Computer, it came with a thick Manual covering nearly everything about the computer. From the registers, how the electronics were wired, to how to code for it.
I cut my teeth coding in the Borland environment, And on its single 5 1/4 floppy had documentation on every command and how to to use them, with a working full example.
But today we get Online documentation, that often doesn't fully explain what you want to do. Gives partial example that don't quite fully work o
Re:You must be new here... (Score:5, Insightful)
I've seen too many examples of "using" an API that are such primitive toys they might as well not exist. At least with open source you can figure out how the API ought to be used.
Re: (Score:2)
Wow... (Score:5, Insightful)
That is staggering really, especially with a company that has the resources that Apple does. I've had to develop and implement an API against a third-party SQL DB app we employ. And it wasn't too much of a stretch to include XML comments around each endpoint and its methods, which automagically created the API "help pages." So there was more than enough description, examples, etc. Even if I just a handful of internal staff will be the primary API consumers of my project, you have to consider down the road. Now scale this out to Apple, with countless API consumers.
Not to mention there are always some API gotchas that arise, in terms of potential differences in API request query syntax, what elements are coming back in the API responses, etc. Those alone are things I've had to self-document when I encounter them with third-party API services!
Re: (Score:2)
I wonder if its intentional. Now that they've established a huge user base for their walled garden they're filling it with water for the developers to sink or swim - either you're a large monied interest who can really pay for the prestige of getting your app to work on Apple's lemons with teams of programmers reverse engineering APIs all day, or... you aren't.
Yep (Score:5, Interesting)
Yep.
Sounds about right.
The annoying thing is that at one point Apple had great documentation with a ton of examples, but at some point they deprecated all of it and now half the time you look up the answer to some question you get a link back to the old "archived" documentation which, thanks to the fact Apple frequently removes old APIs entirely, is just flat-out wrong.
Swift makes things even worse because it's sort of a magical mapping between the "real" Objective-C APIs and the Swift API - which means that symbols change between Swift versions. That thing that used to nsSomeValue? Well, now it's someOtherValue. That enum constant you were using? It's just gone. Good luck figuring out the new way to do it.
The other thing is that even when "documented," frequently the documentation is worthless. "UIFooBar.quz - the FooBar's quz." Well, gee, thanks.
It gets even better when you have APIs that behave differently in the iOS simulator environment than they do on a real device. (As an example, HealthKit provides dummy data in the simulator, which does make sense - except the dummy data it provides in no way matches real data. How's it different? Well, HIPAA means I probably couldn't tell you if I knew, except HIPAA also means I've yet to find out because no one will tell me, either.)
Re:Yep (Score:4, Informative)
The annoying thing is that at one point Apple had great documentation with a ton of examples
Indeed. That was one of the things that encouraged me to move from the Microsoft world to the Apple world. I was growing increasingly frustrated with Microsoft's push to make programming more and more complicated, as well as a revenue stream, whereas Apple was encouraging it for free and provided the thorough documentation to back it up. I was amazed one could create rich, graphical applications on the Mac that went way beyond the widgets of Visual Basic (what I was using at the time).
But sadly I grew just as frustrated with Apple as everything kept changing, API's were depreciated, and documentation went out the window. Now, I focus my attention more on Python. The myriad of modules make documentation a bit of a quagmire, but at least I'm able to get the answers to my questions.
Re: (Score:3)
in re: symbols change between Swift versions
In Apple's defense, xcode does a pretty good job of dealing with this issue. Clicking on the error in xcode has always presented me with an option `symbol foo has changed to bar, fix it?'. Annoying as this issue is it's easy to deal with.
Re: (Score:2)
Clicking on the error in xcode has always presented me with an option `symbol foo has changed to bar, fix it?'. Annoying as this issue is it's easy to deal with.
Unfortunately AFAIK that support only goes back two previous versions of Swift. (Or at least the ability to auto-convert to current Swift definitely did - I remember wanting to use an old library that turned out to be "too old" for Xcode to auto-update. I don't remember the exact end result of that, I know we ended up not using the library but I think it was because we dropped the feature that would have used it anyway.)
I also remember running into this issue when trying to use answers to Grand Central Disp
Re: (Score:2)
The short answer is that my own health data won't help with what we're trying to do with HealthKit. The longer answer involves explaining exactly what we're doing, but I think it's safe to say it involves health data from people who have specific illnesses, which makes my own data and the generic sample data kind of useless.
Documentation if latin for useless paper work (Score:3)
In absolutely no meaningful order:
1. Microsoft - Broken examples, incorrect procedures, meaningless explainations
2. Google (I usually end up on Stackoverflow).
3. Telerik (just don't even bother).
4. ESRI - It's not actually bad, but it can be frustrating, although the forums are good.
5. Microsoft - Seriously it's BAD.
6. Open Source Projects - Not all of them, but in the vast amount of cases the documentation is non-existent or written so it is.
6. JavaScript / TypeScript examples - It's one Stackoverflow post modified 10 000 times and it's still broken.
7. GO - Not actually that bad, but a lot of mistakes - granted it's community driven and the community is excellent.
8. Microsoft - Why do they even bother?
I don't see the point on continuing, the point is that many companies / communities have border line unusable documentation, and we've just come to accept that. Our company recently put out a SDK and luckily I got a hold of the documentation before it left, because it was horrible, and now it's almost border line passable. As a developer / engineer, I've come to the realization that documentation is Latin for useless paper work, because in the vast majority of circumstances I'm figuring out how to do the job to spite that paper work.
Re:Documentation if latin for useless paper work (Score:4, Interesting)
If we are exclusively limiting conversation to API's I've worked with Microsoft for awhile now. Looking over their Graph API, I didn't find it to be necessarily turrrrible --> https://docs.microsoft.com/en-... [microsoft.com].
When it comes to digging into their .NET documentation, likewise I didn't find it to suck too hard. Here's just one example --> https://docs.microsoft.com/en-... [microsoft.com]. If you notice, you can pull the drop-down to change versions and the result doesn't really limit the useful info you are getting back. Unlike Apple, as their newer API versions leave little details.
Just my $0.02 USD.
Re: (Score:1)
And then you need to code against Exchange with encryption/decryption....
Documentation is barely existing, most documentation and blogs from MS professionals are wrong. You'd better take the word from the developer of 'OutlookSpy' as gospel, at least then you'll experience progress.
Re: (Score:2)
As I haven't had to work with Exchange encryption/decryption, I can't speak to that particular area. And I hear ya, the times I've resorted to Microsoft blogs I too have found them to be a) outdated, b) lacking, c) just plain wrong, d) all of the above. Better off searching StackOverflow really.
You can work with Exchange (at least Exchange Online on Microsoft 365) using Microsoft's Graph API --> https://docs.microsoft.com/en-... [microsoft.com]. I have had projects creating my own third-party sync using Graph and found
Re: (Score:2)
With .net core, which is becoming .net 5, if the documentation is bad you can clone the source code and work out what it actually does. Then, if you are feeling charitable, clone the documentation and submit a pull request to fix it.
Or at least raise an issue against either repository pointing out the problem, hoping someone else will fix it.
An open communication channel with the developers makes a world of difference.
Re: (Score:2)
(Submitted too soon) There's even an edit button on the documentation page that links directly to github.
Re: (Score:2)
Source code is the 2nd best documentation (Score:3, Insightful)
Old man reminsicenes (Score:5, Informative)
I can remember the days of system documentation being more or less complete, along with detailed explanations of error codes and messages. It even came with the computer system, nicely bound and broken into sections.
If you had access to the official documentation, there was little you couldn't do or fix because the documentation told you how to use it and what the actual errors meant.
Now it's an utter shit show, with various Unix manpages about as good as it gets and most for-profit PC vendor documentation being somewhere on a continuum from "barely useful" to "basically wrong" and often completely missing.
This was a development you could kind of live with when systems actually delivered GUI tools that let you perform a majority of the tasks. Now that we're diving into an era where the GUI is only 20% feature complete and the rest is a shitshow of Powershell modules and their like, it's simply awful.
Re: (Score:3)
Re: Old man reminsicenes (Score:2)
The same principle applies today with software. I've been told my documentation is really good by my team. The reason is that I do ops engineering. If a developer doesn't understand how to use the devops tools, I am the one person they will go to for support. I don't have time to re-answer questions over and over, so I write good documentation and just point people at the docs.
Re: (Score:2)
Re: (Score:2)
I never had any of the common 8 bit computers at the time (Spectrum, Commodore 64, etc.) but it seems they did have fairly complete documentation. Granted, on the old days things were much simpler: software fit in KBs or MBs and the APIs were so simple and few that it really wasn't that much work to document them.
But yeah, current systems could have much better documentation. It just seems most companies can't be bothered to hire
Re: (Score:3)
The ones with the best documentation were of course "real" mini or mainframe systems. I had some experience with CDC Cyber mainframes (they were the state educational platform of choice through high school and college), and I remember seeing rooms with a complete set of documentation, like an entire wall filled with binders of documentation.
Now mind you, this was just for the operating system, operating system applications/tools and functionality documentation for any vendor-supplied compilers. Not any th
You're not supposed to be tinkering with the APIs (Score:4, Insightful)
You're supposed to take your code down to your local Apple Store, and for a fee they'll write the interface code for you.
Re: (Score:2)
Saddle up to the Genius Bar, where a snyde little millenial with a man-bun in a black turtleneck can show you his leet skillz....
Re: (Score:2)
You're supposed to take the API usage idioms used in tutorials, and copy and paste them into your production code. Apparently.
Re: (Score:2)
There is far more truth in this than there should be, in philosophy if not fact. Apple is for consumers/consumerism, developers are just a necessary evil anymore. Geek friendliness left the building with Woz.
The drawback of claiming code is self documenting (Score:4, Insightful)
First, Apple should hire some fucking tech writers and just fix this problem. It's not a problem that should exist. But it might exist because so many programmers drink the kool-aid of believing their code is 'self documenting'. In context, a lot of code IS straight forward, but getting out of the habit of documenting what you're doing makes the task of publishing API documentation that much harder. If you're told to document as you go and keep it up to date, not taking for granted that everyone will understand your clever code, you'll have something rough but serviceable to hand off to a tech writer to clean up later.
There are lots of clever programmers out there doing clever things that are totally opaque to anyone coming along later; the skill to describe what they're doing simply is lost, or worse, derided as unnecessary. This mentality pollutes the pool, and pretty soon everyone is unwilling to explain themselves at all, and you get hundreds of programmers wasting time deciphering stupid tricks instead of building on top of a clearly documented system.
I'm in the games industry and documentation is terrible; non-existent in internal systems. Nothing is provided as an API, you just grab whatever from wherever, and you never really know if what you're doing is the right way because there's no clear indication whether what you're using is the best tool for the job. Everything is folklore and oral tradition, and sometimes you find out later that you should've been using a completely different system all along.
But seriously, it's an embarrassment for Apple to have so much money and depend so heavily on development for their devices, and not be able to present a clear and well documented API. Someone really needs to get on C-Fed's case about this.
Re: (Score:2)
Good coders need good PAs (personal assistants) who can interface with management, other teams and tech writers.
If your rock star coder doesn't have a PA, you are wasting resources. Teams of senior coders and engineers a should also have a shared PA. A ratio of about 6 to 1 seems to work best.
Good documentation often needs a librarian to organize it. The only sane wiki out there is Wikipedia because there are so many proper librarians to keep the data organized. Most wikis are like a library without a c
Re: The drawback of claiming code is self document (Score:2)
I don't know why this concept is so hard for employers to understand. It's so obvious that this saves money and improves productivity.
trial and error and more error (Score:1)
Too many things are becoming "organic" in our industry. [slashdot.org] It's not just Apple. Precision, logic, and clarity seem dead. The tools of yesteryear had shorter learning curves and one got more done*. Bloated teams of specialists are needed for relatively simple apps now. It's not just nostalgia, it takes more finger movements and code per domain feature. The cost of choice of large. You have a lot of wonderful options, but they often don't play well together an
Re: (Score:2)
Sure you don't want to throw a "get off my lawn" in there somewhere? I hate to be the one to break this to you, but in an age of smart phones, tablets, and computers with screens of every size and description, the days of fixed 80 column by 25 row screens is officially over.
Heck, even the comment of "when most biz users actually use it on a PC" doesn't make sense. What screen size is that PC? 640x480? 800x600? 1024x768? 1280x960? 1440x960? 1600x670? 3440x1440? Or have they rotated the silly thing into portr
Re: (Score:2)
The Pros use multiple monitors, 2 or 3 in portrait mode and 2 in landscape. The landscape as joined desktop and the portraits as individuals ...
Just Apple? (Score:2)
Docs are now unfashionable (was: Just Apple?) (Score:3)
I don't see Apple leading but rather following a long-term trend who's end, if not intent, is reduced self-sufficiency of the consumer.
Quality of documentation has been in decline for 50 years. Take a look at an owner's manual for a piece of technology or a major consumer appliance from 50 years ago. You'll see detailed parts lists, beautiful "exploded" assembly drawings, often schematics, and a "theory of operation" section--all things that are hard to get in a service manual today (if such a manual even e
Re: (Score:3)
I have an old o-scope. The documentation includes a wiring diagram, parts list, and troubleshooting information. I admined AT&T 3B2g minicomputers running System V. It came with a stack of books that contained everything one could need to know.
At work right now, I am supposed to install a third party product. The installation manual is 200 pages and is clear as mud and the install has failed several times already for reasons that are not clear or requirements that are not listed in the inst
A bit of a silly rant (Score:3)
It is a bit of a silly rant. I've done quite a bit of Apple development and I found their documentation much better than, say, Google's. It is correct that it has degraded in the last few years and we probably have to blame Swift for that (both because they had to start keeping 2 versions of docs and because Swift took a long time to stabilize), along with the tendency to deprecate and/or change things sometimes really needlessly (like changing the names of enums from FooBar to BarFoo etc - again it is more common with Swift). But, again, even now their documentation is not really bad compared to some platforms I had to work with. E.g. the example linked to is still beta, so it will probably get documentation (note the "deprecated" function claims availability up to iOS 14, which is the currently latest released).
If I wanted to rant, it would probably be more about so many problems over the years with their itunesconnect site and submission process, the arbitrary rejection of binaries over absurdly "imaginative" (i.e. flat out wrong) interpretations of their own rules - to which if you appeal they double-down, the weird issues of the APIs themselves that can have bugs which even if you report Apple might still just tell you they are designed that way (you are using the API wrong). I have many examples, but in the end of the day their documentation is not bad in comparison and the whole development might have these issues I mentioned, but if I compare it to, say, BREW development (Verizon Get It Now if you recall), it like heaven!
Re: (Score:2)
At a glance, almost everything seems massively out of date. Security, networking, drivers, kernel, with modification dates from 2014 to 2018, and some even older. Basically, it almost looks like nobody is maintaining anything except for SwiftUI.
Don't get me wrong. I'm not surprised — teams at Apple always focused on the new hotness — but there were historically always a small percentage of engineers who cared enough about users, developer, etc. to make sure that existing technology wasn't co
Just Apple doing what Apple does (Score:1)
I don't find it that bad... (Score:3)
I've been doing iOS development since before the launch of the App Store...
I don't see Apple's documentation as being that bad, especially compared to other systems. Have you ever tried to find current and accurate documentation for React Native for example...
Even the "No Overview Available" sire you linked to shows this. Most of the API's people actually use have green bars, and something like 95%+ overview coverage. The things that are read are ones like FWAUserLib, which I've never even used... the only one there that probably should be documented more heavily is SwiftUI but even there it's under pretty constant development and there is a to of third party docs around that.
Do far as I can tell from various developers I follow on social media, Apple docs seem a bit ahead of most everyone else - even at Microsoft, once the king of docs, you know find scores of dead links and other pretty terrible doc problems. At least Apple docs are pretty clear, easy to follow, and do a pretty good Jon with providing Swift and ObjC examples as well.
Inside Macintosh (Score:3)
Remember the good old days?
Re: (Score:2)
Yeah, I was going to bring this up. I was a early, bright kid and I can't even remember my first true programming book (although I know it was before age 8). However my first official *documentation* book was... drumroll please... Inside Macintosh, VI. The billion-page version covering System 7.
That thing was a behemoth, and I still have it somewhere in storage (probably to keep my bookshelf from floating away). But it was clear, logical, well-formed, and easy to understand, and it was a great introduction
I'm astonished to hear (Score:2)
Sigh (Score:2)
Function name and prototype.
Parameters (including links to variable types involved), including type and short description of each parameter.
One-liner of what the function does.
More general description of what it does, what it expects of the parameters, restrictions on its use, caveats, warnings, etc.
One short copy/pasteable real-code example of its use for all parameters, and more examples if it has lots of parameters which may vary how it operates on those parameters. And if the function is part of a larg
Re: (Score:2)
You want an example for a function call? Seriously?
Remember the 1984 commercial (Score:2)
IBM manuals tend to have This page intentionally left blank
It appears that the circle is now complete
Make xcode standard (Score:2)
This Article is 20 years too late (Score:2)
Apple's focus (Score:2)
Is on consumerism and trying to stay "hip". Everything else is secondary or lower, including build quality.
Apple doc USED to be the best... (Score:2)
Anyone here remember "Inside Mac" published by Addison Wesley? Best documentation i've ever read. Covered every single API, and every nuanced usage of each. Apple has ... fallen very, very far from it's own tree...
And don't get me started on "Apple Human Interface Guidelines", one of the blood vessels in my forehead might just "let go"...
Write a fucking book! (Score:2)
We had to do it in the 80ies as well, even if we still got 20 pounds of manuals with everything.
Or perhaps just read 'Apple for Dummies'.
Not sure, since I can't possibly RTFA.
Get help from your community (Score:2)
Re: (Score:3)
I had an undocumented update compatibility problem with HP printer drivers recently. Their forum contained hundreds of "me toos" from others with the same problem, it had several wild guesses on fixes from people who didn't have the problem and hadn't tried what they were suggesting, it had a few log files and configuration dumps that might help the developer of the closed-source driver figure out the problem, and notably, it had zero official answers, nor answers from anyone who had authoritative knowledge
PHP (Score:2)
The best documentation system i've seen has been PHP documentation system where the community can chat/discuss each operation/method. This results in focused discussions, problems, tips and solutions per operation.
Nothing else has come close to this.
Re: PHP (Score:2)
I like the PHP doc chats. The level of incompetence demonstrated within rises to the level of comedy.
Re: (Score:3)