16 ms·

We need to document macOS

245 points by fern12 9y ago

unkown-unknowns 9y ago
> Yet Apple’s documentation for users and those supporting users has all but dried up You and me we both RTFM, but the population at large? Not so much. When computers were in their early days more of the people that used them were willing and even interested to learn a lot about what was going on. Now the computer is a tool used by most people to do specific tasks. Just like I don't care to learn how to fix my car they don't want to learn how to troubleshoot software nor hardware problems with their computers. So it might not make economical sense for Apple to spend any significant amount of money on employing technical writers.
- pfranz 9y ago
  I think a more common example would be Googling a daemon that's hogging memory or CPU. Ideally, the top result would be Apple docs with a clear, concise description. In practice, it's usually an Apple discussion thread (which I do give some credit for them hosting/maintaining) or Stack Exchange. Although, I don't think I've ever seen an official response in their forums. It's usually a meandering set of posts (and "me toos!") before I can get any description of what it is or how to address it. Sure, the average person doesn't have Activity Monitor (or top) open, but they could be walked through that process when their fans blare and battery life nosedives.
- hollander 9y ago
  Not only that, but when I have a problem with my Mac, I go to Stackexchange and ask my question there. Many times I get a useful answer. Apple could set up a team to help people over there, and officially support it, like Ubuntu does. Documenting is one thing, helping people with their questions is the easy way out.
- ZenoArrow 9y ago
  I'd say it ties up with Apple's focus on being a consumer electronics manufacturer. Apple and Sony have more in common than Apple and Dell.
TrickyRick 9y ago
I find most answers I need on Stackexchange. However there are books like "Mac OS The Missing Manual", I always wondered if anyone bought them and what they actually contained.
- bastijn 9y ago
  My thoughts exactly. First thought was what problems did this person run into that can't be found in a single google hit today? I was thinking the piece would go into some obscure internals but that doesn't seem to be the case. MacOS is simple enough to grasp for most people at first use. More advanced usage is documented, not in one location but scattered over the internet. Google made that not matter anymore. In addition, most documentation you would need today is for the products you install I guess, not macOS. But again, it really doesn't matter much with Google finding anything you search. My experience with (large) documentation projects. They are outdated almost always. Q&A style works much better nowadays.
  - mdaniel 9y ago
    > Q&A style works much better nowadays. I believe that's only true if the questioner is versed in "How to ask questions the smart way," and/or the answerer is _also_ versed in that, so they know how to answer what the questioner was _really_ asking Not to mention the tons of "dear lazyweb, do my homework|task for me, kthxbai" level of effort expended by the questioner
ecma 9y ago
TFA gives two very disparate examples of documentation failures (basic use of the dock vs service management and the init system). What does the author want to write? A book in the style of the For Dummies series? Something more like the Windows Internals books? Both, everything in between? Some of those surely already exist...
em3rgent0rdr 9y ago
Better: We need to stop using undocumented proprietary systems like macOS.
- mvdwoord 9y ago
  In contrast to undocumented free (open) systems? Documentation is an issue irrespective of prorietariness(??!) of a system. I welcome this initiative. (Yes I know there are examples of documentation excellence to be found in some free/open systems. You can advocate their use whilst also having well documented macOs.)
  - ben0x539 9y ago
    I mean, I'm not the target audience and I don't have the attachment to OSX as a platform, but if I was gonna expend the energy to document a thing, I'd hope it goes towards a good cause and isn't just free labor for like the richest corp I can think of from the top of my head.
    - ewjordan 9y ago
      Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux, which nobody plus epsilon uses (except amongst devs). Impact is a big factor in how useful an activity is, even if it's tied to a big company.
      - em3rgent0rdr 9y ago
        > "Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux" From a purely utilitarian perspective: - The same amount of effort spent trying to document will result in more documentation being produced on a free system, since free systems are easier to document. - The same amount of documentation produced will result in more benefit from end users for a free system, because more people will be able to use a free system.
        9y ago
CrazyRabbit 9y ago
https://opensource.apple.com/ https://opensource.apple.com/
- mdaniel 9y ago
  I have a rule that says something isn't truly Open Source unless you can build it, because binary patching is for chumps. Have you tried to build those? There are several projects attempting to do so, and I have yet to experience "download tar, ..., boot that Darwin build in a (qemu|vm)!" for any value of "...".
static_noise 9y ago
When it's documented it cannot be changed as easily, so it's often better to not document everything in detail.
- pjc50 9y ago
  Then your users find that their own memory of where to find things and how to perform tasks is unreliable. Has the system changed or they forgotten it? You're effectively "gaslighting" your users if you rely on this.
  - static_noise 9y ago
    If they rely on you (you being apple here). It's their fault for relying on undocumented interfaces. Consequently, they should stop using your system but they don't.
  - nebabyte 9y ago
    Apple gives users APIs at the level they think users should be operating, not system internals. Are we seriously having this discussion, HN? Did people just wake up today to what their reality has been for years? https://www.youtube.com/watch?v=ilcRS5eUpwk https://www.youtube.com/watch?v=ilcRS5eUpwk
- krylon 9y ago
  On the contrary, that makes documentation especially important so you can figure out if some changed behavior is a bug, a mistake on the user's side, or intended.
- actuallyalys 9y ago
  I agree that there's a trade off between detailed documentation and flexibility, but I think regularly leaving out details to allow for frequent changes can be a red flag. Unless your project is new and in beta, you probably shouldn't be changing things that often. After all, even if your documentation is sparse, users are going to start expecting certain behavior just from using your project. You can also tweak this tradeoff a little. If you explain up front that what you're describing changes a lot and don't put it in the official documentation [0], you can be somewhat detailed and still have room to change. [0]: Think a wiki or blog that your project maintains.
deleted 9y ago
[deleted]
jonnguyen12 9y ago
Are we talking about technical documentation or unofficial user manual? We don't need the latter for sure.
quink 9y ago
Why bother? If the people making the thing can't be bothered documenting it you're going to fight an uphill battle. In the long run, for better or for worse, code is documentation. If the code isn't available there'll be only so far you can go. And with the unification of iOS and macOS fast approaching the number of people able to have transparency into even just the POSIX layer is going to drop another order of magnitude. macOS is dead, Apple just hasn't told anyone about it yet. And iOS 11 is going to be it's murderer. If you have the time to document, you might as well spend the time documenting Windows, BSD or Linux; Blink or Servo. Or the JS ecosystem. The Apple specific SMB implementation or APFS or Cocoa are not worth documenting any more than OOXML would be - only as a specification that one party has the power to change and to implement. There is no way for the documentation to be considered prescriptive rather than descriptive for anyone touching the code. It might be useful in some limited aspect for a limited time, but it will decay as Apple considers every single pixel their OS is going to render to be under their control in some way. Apart from what they can sandbox, which amounts to the web platform, which is plenty documented already. > launchd – second only in importance to the kernel – controlled and orchestrated most of the services supplied in macOS Who cares about the launch facilities in macOS when anyone who should care about launch facilities is going to be using Windows Server, Linux or BSD? Apple couldn't have been saying fuck off to anyone wanting to screw around with CUPS or Samba or launchd more loudly unless they shouted it from all the rooftops in Cupertino. > Magic Trackpad 2, never knew how to launch an app from the Dock, or couldn’t manage their Photos library. 1. It'll stop working (here we go, top result for a Google search: https://support.apple.com/en-us/HT204621 https://support.apple.com/en-us/HT204621) 2. Launchpad exists and has a keyboard shortcut and 3. Photos manage themselves. What does manage even mean in the context of you take a picture with a phone, it adds geotagging and a time and that's it. What more do 99% of users want?
enqk 9y ago
This problem is actually the reason I've fallen out of love with Macos as a platform for my home computers. There's way too much stuff that goes around, daemons that are waking up at any given point and doing a lot of I/O, for which there's absolutely no documentation whatsoever. It kills the performance on my old Macs and also doesn't inspire confidence that I'm a user/owner of the device.
- nebabyte 9y ago
  > and also doesn't inspire confidence that I'm a user/owner of the device ...What gave you that delusion? Are you one of those people who clicks "okay" to EULAs without reading them?
  - kronos29296 9y ago
    Actually you still own the device just not the stuff making it actually useful. That is still owned by apple. (EULA)
vladdanilov 9y ago
Apple's primary focus and the source of money is iOS. That is why macOS has to be 1) just noticeably better than competitors 2) inconvenient enough for average users to partially migrate to iOS.
gogopuppygogo 9y ago
This is Apple we are talking about. If you built a knowledge-base like this on your own time and for the right reasons I bet they send a DMCA.
- bcook 9y ago
  >If you built a knowledge-base like this on your own time and for the right reasons I bet they send a DMCA. Why do you say that? Your post makes me think I'm ignorant of Apple's past litigation.
- Walf 9y ago
  I doubt it. What claim would they have over a non-fiction work they had no hand in creating? They could sue for other reasons but the judge would have to be a fucking idiot to do anything other than order Apple to pay court costs. How much software documentation has been written by third parties?
LeoPanthera 9y ago
Just in case no-one read the leaflets that came with their new Mac, Apple has fairly comprehensive macOS documentation online: https://support.apple.com/macos https://support.apple.com/macos A lot of this is built into your Mac also, at Help > Mac Help in the Finder. For those who prefer physical books, I've always found the "Missing Manual" series to be excellent.
- pfranz 9y ago
  How come I never see them come up in Google searches? I have seen it come up when looking for conditioning your battery or the shortcut keys for Target Disk Mode. But more often I'll search for a runaway process name or an OS message that is spamming Console. The top results are Apple Discussion posts that go on for pages, but often don't have a clear result. I also recently was trying to learn more about macOS' init system and got lost like the article mentioned.
  - extra88 9y ago
    For the processes, it's not that the documentation doesn't exist, it's that they're very low-ranked in search results (and many who know that they're looking for a process name know to try 'man foo' before a web search) [0]. Any documentation rarely describes exactly a problem someone is experiencing but a discussion forum might, so those are the links that come up first in a search. As for message in logs, I don't tend to find those in other *nix documentation either. [0] https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man8/mdworker.8.html https://developer.apple.com/legacy/library/documentation/Dar...
- nottorp 9y ago
  Do they? I don't think the OP (or me, for that matter) is looking for documentation telling him where to click in the UI. The article seems to be about more low level stuff.
dredmorbius 9y ago
I hope the author of this site is proud of their fixed-position page header. Because it takes up fully 1/4 of the screen height in my browser. Just sayin'.
zalmoxes 9y ago
If you haven't already, join the MacAdmins Slack. https://macadmins.herokuapp.com https://macadmins.herokuapp.com It's an open-invite slack team with over 12000 users - sysadmins, MDM developers, security researchers and so on. We have various ongoing efforts to document and improve the macOS experience for users. If you have a macOS question, you'll likely find the answer there.
- mdaniel 9y ago
  > you'll likely find the answer there Well, I hope the Google Bot (plus whichever one DDG uses) also has an invite to that proprietary, closed, messaging system, or that the "macadmins" owner has set up a channel mirroring system ala IRC web logs, otherwise the system you described isn't contributing to the open body of knowledge. Related, although mildly off topic, :fu: slack search
natch 9y ago
To the author, did you file radars listing specifics of which areas you need documented? https://bugreport.apple.com https://bugreport.apple.com isn't just for bugs.
stuntkite 9y ago
OT a bit but I think still related. 8 years ago when I switch to OSX I was furious with finder. Tiny window, no hierarchical browsing and the search just doesn't do shit that is useful. I normally default to locate or find now so much that I was using it the other day I was reminded about how much it sucked. It's literally identical (aside from tags and labels) to what it was forever ago and is a terrible paradigm. I looked around for a bit for some help on refining the search sensibly and nothing in the OS helped (back on topic!). I've been using a great replacement for Finder called PathFinder that does everything Finder should do, but you can't swap it out. All the native places I access Finder are important inroads. They used to have instructions to hack it but apple shut them down. I feel more and more like UI and usability innovation totally ate itself and died at maybe a specific moment in time ~6 years ago. Where did the people and companies go that do cool new things? Are the giants on their laurels long enough yet to get eaten? I'd switch totally to Ubuntu or Mint for my desktop work, but I do things that require the adobe suite, I need a trackpad that works as well as the mac one without fighting it, and I want to just solve problems, not fiddle with barely supported gizmos for weeks. Did we reach the absolute end of all we can do with this juggling of rectangles that display and accept text and now we just get everything that matters to a power user stripped off for the sake of what "most users care about"? I really don't think we have. I'm still pissed and I still have no answers. My kingdom for a $3000 laptop that "Just works" and helps me murder code, deployment, graphic arts, music, and still loads HBONow.
- pampa 9y ago
  A beefy windows workstation or laptop to cover Adobe & DAWs + VMWare for Linux. With fullscreen VMWare and open-vm-tools I can barely notice that it doesn't run bare metal, and i can keep different distros at hand for different purposes.
  - stuntkite 9y ago
    I bought Windows 10 Pro last year and had really high hopes for it after the Ubuntu shim was introduced. Windows is a fucking nightmare for anything involving producing audio at a pro level. The Ubuntu shim does not solve what I need even though it's a nice add. The real kicker is that STILL many errors produce a window where I can't even fucking copy the output. Why that is still a feature, I have no idea. That coupled with how they manage fixes/updates and a general distrust for the system being close to secure... It just didn't work out. I wanted to buy that giant drafting table computer with the knob and say fuck it to the MBP. I went to look at it and bought another kinect one day, and what felt like an omen, their windows run point of sale system that tries to hide in the desks like the apple store failed so bad at taking my card that the guy had to use two different work stations and literally was "turning it off and on again" with both his card swiping windows mobile phone and the computers. I feel like my future is in some sort of hand rolled main LXD or CoreOS or the like, that quickly composts whole systems locally and in the cloud but also easily remote desktops to local Mac and Windows machines. I have ideas in my head and a bit in code for a bare bones graphical interface that renders a graph that I can attach arbitrary points to that go to systems, API, terminal instances, containers, etc. I can weight the node connections and also record weight on paths based on frequency of traversal enabling automatic access shortcuts. Of course OSX is close to impossible to run virtualized, which is stupid as hell. Actually if it could without a larger time investment than my full time job that might solve all of my problems. I don't know, I still need all of the systems that are out there... but I think it's time to put a top layer interface on it that gives me them and more. Setting up a springboard for something that doesn't sit around waiting for big providers to bless me with mana from heaven while they wave their dicks in my face. Here's an example of a nerfed version of what I'm talking about as an OS supervisor UI that I'm using for a lesson series on Docker [https://www.dropbox.com/s/be4lh1015y305jr https://www.dropbox.com/s/be4lh1015y305jr]. There is nothing about it that's clean or safe to operate, but I just wanted to prove it. In the current version you can select a node and drop to a terminal inside of a container. Also, I've added support for API nodes auto generated from graphql and REST (if you write the schema). I think it proves the concept. The next step is the pullback to whole systems I guess.
aurelien 9y ago
Read the FreeBSD documentation ... you'll get it ;-)
schappim 9y ago
>> "I am also daily reminded of Apple’s wholesale failure to provide consistent and complete documentation of its flagship product." The author of this article fails to realise that the Mac is not Apple's flagship product anymore...
walterbell 9y ago
Open-source documentation (PRs requested!) on macOS security & privacy: http://www.oss.io/p/drduh/OS-X-Security-and-Privacy-Guide http://www.oss.io/p/drduh/OS-X-Security-and-Privacy-Guide "... a collection of thoughts on securing a modern Apple Mac computer using macOS (formerly OS X) 10.12 "Sierra", as well as steps to improving online privacy. This guide is targeted to “power users” who wish to adopt enterprise-standard security, but is also suitable for novice users with an interest in improving their privacy and security on a Mac."
- phatbyte 9y ago
  This is a great resource. A lot of things I didn't even know.
sigjuice 9y ago
How can outsiders even begin to effectively maintain documentation for obscure macOS things like DAS and CTS? I can't be the only person who has never heard of these before.
SwellJoe 9y ago
When I did some work on porting out product to macOS (so developers could run their server environment locally, though a few loons wanted to actually run macOS on servers), I was immediately struck by how awful and incomplete the documentation was. And, I've been working in the Linux world for a couple decades...where docs are copious but wrong about 50% of the time. In particular, the service launcher (launchd, mentioned in the article), and various other system level things (including logs, also mentioned in the article), have so little official documentation as to be laughable. You just have to spelunk the web to find someone who has the tribal knowledge and has shared it in some form. I gave up on the task, as the level of pain was far too high. But, I'm kinda baffled why anyone would volunteer to provide free labor to one of the largest and most profitable companies in the world. I give away tons of my time for OSS, but I'm not about to get out and push if I've paid for a luxury car. I'd rather put my time into something that is free and open for everyone, including my future self. Actually, the word "rather" isn't strong enough: I would never give my labor to an $820B corporation.
- igravious 9y ago
  > But, I'm kinda baffled why anyone would volunteer to provide free labor to one of the largest and most profitable companies in the world. I give away tons of my time for OSS, but I'm not about to get out and push if I've paid for a luxury car. > I'd rather put my time into something that is free and open for everyone, including my future self. Actually, the word "rather" isn't strong enough: I would never give my labor to an $820B corporation. That's exactly what springs to mind. Why should we do Apple's work for them when they are swimming in cash reserves. It beggars belief that anyone would suggest this. Obviously their pain is so great, they're so tightly shackled, their alternatives so limited, that they would rather willingly donate their labor to a wealthy corporation than attempt to take said corporation to task or shock horror jump ship.
  - captainmuon 9y ago
    It's not Apple's work to do. It's not in their interest to document everything. What applies to internal APIs applies to lesser extent to the detailed workings of the OS, like the init system, themeing, etc.. If it is documented, people will depend on it, or write low-level tweaking tools that Apple doesn't want to exist. What is good for customers and developers might not be good for Apple, and vice versa. (A separate issue are the user docs, e.g. how to use Finder. I guess they are good enough, I haven't found the need for such docs.)
nebabyte 9y ago
> We That would be Apple's job, and if you're waiting for them to make it easier for third parties to work on the system they think rightfully are theirs alone to develop, don't hold your breath. Did we all start taking amnesia pills or something? You knew what you signed up for.
seba_dos1 9y ago
No. It's Apple who needs to do that. This isn't a free software project - lack of documentation is an argument for abandoning the platform, not for starting a community project of doing work for Apple for free.
- pebers 9y ago
  I guess the problem is that Apple don't need to do it; lots of people would like them to do it, and maybe they should do it, but it's not hurting their bottom line much so they can just continue as they are. Unless a whole heap of customers suddenly decide to buy different laptops instead over it, but I'd not be betting on that.
  - hobarrera 9y ago
    Arguably, this might happen in the long run. They might slowly lose dev over the years if they neglect documentation, which will eventually hurt the app ecosystem. Eventually, that'd affect user. Very hard to say if the problem is serious enough yet though.
- dethos 9y ago
  Indeed, the responsibility belongs to the company that is providing the proprietary software/product. Otherwise it would send the message that good documentation shouldn't be provided because the "community" will handle it for free.
yannovitch 9y ago
There is a saying in French which says that half of the treatment to get better is to recognize/admit you're sick . There is an other saying which says "Faute avouée est à moitié pardonnée" (If you admit a flaw/mistake, you're already half the way through forgiveness). That to say that maybe there is a lack of documentation because Apple would have to admit to itself (...and to the world) that macOS is not the absolutely perfect OS without any flaws, virus/malware, or room for improvement, that they want all of us to believe.
- sd8dgf8ds8g8dsg 9y ago
  > There is a saying in French which says that half of the treatment to get better is to recognize/admit you're sick I believe this comes from the 12 step program of the Alcohol Anonymous (religious sect). 1. We admitted we were powerless over our addiction - that our lives had become unmanageable.
st3fan 9y ago
Launchd documentation: https://developer.apple.com/library/content/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html https://developer.apple.com/library/content/documentation/Ma... See more documents linked at the bottom of that page.
- blablabla123 9y ago
  Nice, XML config. I wonder if Apple employees are internally allowed to voice criticism.
  - JeremyBanks 9y ago
    Plist files have XML, binary, and JSON-like serialization options, and have been in use for longer than JSON has existed. Any Mac developer will be familiar with them, and have access to multiple APIs for handling them. Of all the things in MacOS to criticize, this is just ignorant.
st3fan 9y ago
End user docs about The Dock: https://support.apple.com/en-ca/HT201730 https://support.apple.com/en-ca/HT201730 More links at the bottom
st3fan 9y ago
How to charge you Magic Trackpad: https://support.apple.com/en-us/HT205160 https://support.apple.com/en-us/HT205160 Also included in paper documentation in the box.
- jsz0 9y ago
  There's also a low battery notification that says something like 'plugin a Lighting cable to charge'
jalcazar 9y ago
"We"?? Maybe we as customers of Apple should demand Apple to better document macOS. Apple can well afford to get the documentation fixed.
extra88 9y ago
The author seems confused. Launchd is a service for starting processes (on boot, on other events, or on a schedule), Centralized Task Scheduling (CTS) is a low-level API used only by developers writing native code to perform tasks within a process [0]. CTS can only be used by a running process while launchd is a running process you can instruct by loading .plist files (normally they're only loaded at boot from LaunchAgent/ and LaunchDaemon/ directories). [0] https://developer.apple.com/library/content/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/DiscretionaryTasks.html https://developer.apple.com/library/content/documentation/Pe...
cptskippy 9y ago
For all the things that Microsoft takes flak about, this is one of the few areas you really can't complain much about. They maintain detailed versions documentation and make it easy to explore. Every so often I come across something that isn't documented well or at all and it hurts. But it has a page at least and on every page they have a public feedback mechanism.
- diego_moita 9y ago
  Not only that but also tooling (Visual Studio) and community development(Codeplex, Codeproject). The Android ecosystem is not bad, also.
charlesism 9y ago
> I don’t know how many technical authors were employed > by Apple at that time, but I suspect it was a > far higher proportion of total staff than it is now. Or maybe the proportion is the same, but Tim's shorter release cycle has resulted in the OS permanently being in a state of churn.
userbinator 9y ago
Apple has always been vague and stingy with the documentation; despite the author mentioning this, In the days of classic Mac OS, when print publishing was growing as a result of Macs, Apple published an exemplary series of books under the banner Inside Macintosh I have read the Inside Macintosh books but they still felt somewhat incomplete and superficial (although they're definitely a little prettier) compared to what I'd consider close to a "gold standard" for documentation, the IBM PC/AT Technical Reference and the same one for MS/PC-DOS. I suppose it had a lot to do with the general attitude of Apple's culture, summarised in the famous phrase "it just works". The notion that systems should be designed to be so easy to use and obvious as to require no documentation, has resulted in a lack of documentation even for those cases which are not easy to use nor obvious.
- pvg 9y ago
  I have read the Inside Macintosh books but they still felt somewhat incomplete and superficial (although they're definitely a little prettier) compared to what I'd consider close to a "gold standard" for documentation, the IBM PC/AT Technical Reference and the same one for MS/PC-DOS. One of these is a foot of big books documenting a GUI system and its components, the other is a single volume that tells you handy things like 'The PC/AT has three programmable timers'. I don't think the documentation was ever complete but Apple did produce a lot more of it and had a lot more to document to begin with. The level of documentation is not really directly comparable let alone a symptom of some non-existent 'just works' culture and attitude. If anything, one could make a reasonable argument Apple of the time spent too much effort on beautifully documenting piles of things that were ultimately not useful or successful.
Gracana 9y ago
Does anyone remember "Inside Macintosh," the manuals Apple published back in the classic Mac OS days? I have many of those books, covering everything from how the hardware handles drawing to the screen, up through memory management, files, networking, etc. They're examples of some of the best technical documentation I've ever encountered. It's too bad they don't prioritize that anymore. :(
- scott_karana 9y ago
  I remember reading about them in the second paragraph of the article... ;-)
  - Gracana 9y ago
    S'not the same to read about it. If you're interested in documentation writing I recommend looking for some of Apple's older stuff on archive.org to see what it's like. I don't see much documentation written in their kind-of extended style these days... A lot of documentation seems to be either terse or tutorial-y, there's not much that tries to focus on the concepts relating to / the purpose of a given feature.
e28eta 9y ago
It's old (circa 2006) and really low level, but I loved reading through Mac OS X Internals (http://www.osxbook.com http://www.osxbook.com) If it were updated, or a vol2 was released with all the new stuff, I would immediately buy it. It's not going to teach you how to use Finder, but you'll have a great understanding of the internals.
qualitytime 9y ago
No we don't have to. Stop consuming proprietary code from for-profit corporations.
dman 9y ago
I just wish apple would stop breaking gdb every release. They need to make up their mind on whether OS X is a general purpose OS intended for developer use or if its just a locked down version of iOS which runs on larger devices.
- pjmlp 9y ago
  It intended for OS X and iOS developers, which use the official supported debugger, lldb.
  - dman 9y ago
    In other words writing systems software for OS X if you are not employed by Apple is a fools errand?
    - pjmlp 9y ago
      No, a fools errand is to buy a Mac and use GNU/Linux tooling instead of the official OS X SDK tooling. GDB stop being part of the official modern SDKs quite long time ago.
      - dman 9y ago
        I understand that gdb is not part of the official SDK. I would expect an OS in widespread use to not break userspace and when it does, take substantial remedial action to fix / patch widely used applications.
        pjmlp 9y ago
        The onus is on gdb developers to keep up with the OS API changes, not the other way around.
        dman 9y ago
        If the changes are well documented and communicated ahead of time, then sure I agree with you. Am also curious now what Apple uses to run cloud services - ie do they use OSX as a server operating system themselves.
doubleshame 9y ago
Here are some docs http://images.apple.com/server/docs/Command_Line.pdf http://images.apple.com/server/docs/Command_Line.pdf https://www.apple.com/jp/server/pdfs/Mac_OS_X_Server_v10.2.pdf https://www.apple.com/jp/server/pdfs/Mac_OS_X_Server_v10.2.p...
unicornporn 9y ago
> I am also daily reminded of Apple’s wholesale failure to provide consistent and complete documentation of its flagship product. Well, I'd argue macOS is not their flagship product. Apple makes their money from selling phones these days. I think they have better things to do than to document a marginalized OS.
Joeri 9y ago
The most profitable software company ever still can't build software properly (meaning: fully documented). Does this mean that it is impossible to build software properly at scale? Or is it just that you don't become that profitable without cutting a few corners? (In my original comment I said "most profitable company", but it seems the dutch east india company gave them a run for their money. So, good news for apple, they still have room to grow.)
topbagsvk 9y ago
MacOS users don't need to document macOS as a volunteer project. http://www.bagswalletsit.com/hermes/scarves.html http://www.bagswalletsit.com/hermes/scarves.html

245 points by fern12 9y ago

> Yet Apple’s documentation for users and those supporting users has all but dried up You and me we both RTFM, but the population at large? Not so much. When computers were in their early days more of the people that used them were willing and even interested to learn a lot about what was going on. Now the computer is a tool used by most people to do specific tasks. Just like I don't care to learn how to fix my car they don't want to learn how to troubleshoot software nor hardware problems with their computers. So it might not make economical sense for Apple to spend any significant amount of money on employing technical writers.

pfranz 9y ago
I think a more common example would be Googling a daemon that's hogging memory or CPU. Ideally, the top result would be Apple docs with a clear, concise description. In practice, it's usually an Apple discussion thread (which I do give some credit for them hosting/maintaining) or Stack Exchange. Although, I don't think I've ever seen an official response in their forums. It's usually a meandering set of posts (and "me toos!") before I can get any description of what it is or how to address it. Sure, the average person doesn't have Activity Monitor (or top) open, but they could be walked through that process when their fans blare and battery life nosedives.
hollander 9y ago
Not only that, but when I have a problem with my Mac, I go to Stackexchange and ask my question there. Many times I get a useful answer. Apple could set up a team to help people over there, and officially support it, like Ubuntu does. Documenting is one thing, helping people with their questions is the easy way out.
ZenoArrow 9y ago
I'd say it ties up with Apple's focus on being a consumer electronics manufacturer. Apple and Sony have more in common than Apple and Dell.

TrickyRick 9y ago

I find most answers I need on Stackexchange. However there are books like "Mac OS The Missing Manual", I always wondered if anyone bought them and what they actually contained.

bastijn 9y ago
My thoughts exactly. First thought was what problems did this person run into that can't be found in a single google hit today? I was thinking the piece would go into some obscure internals but that doesn't seem to be the case. MacOS is simple enough to grasp for most people at first use. More advanced usage is documented, not in one location but scattered over the internet. Google made that not matter anymore. In addition, most documentation you would need today is for the products you install I guess, not macOS. But again, it really doesn't matter much with Google finding anything you search. My experience with (large) documentation projects. They are outdated almost always. Q&A style works much better nowadays.
- mdaniel 9y ago
  > Q&A style works much better nowadays. I believe that's only true if the questioner is versed in "How to ask questions the smart way," and/or the answerer is _also_ versed in that, so they know how to answer what the questioner was _really_ asking Not to mention the tons of "dear lazyweb, do my homework|task for me, kthxbai" level of effort expended by the questioner

ecma 9y ago

TFA gives two very disparate examples of documentation failures (basic use of the dock vs service management and the init system). What does the author want to write? A book in the style of the For Dummies series? Something more like the Windows Internals books? Both, everything in between? Some of those surely already exist...

em3rgent0rdr 9y ago

Better: We need to stop using undocumented proprietary systems like macOS.

mvdwoord 9y ago
In contrast to undocumented free (open) systems? Documentation is an issue irrespective of prorietariness(??!) of a system. I welcome this initiative. (Yes I know there are examples of documentation excellence to be found in some free/open systems. You can advocate their use whilst also having well documented macOs.)
- ben0x539 9y ago
  I mean, I'm not the target audience and I don't have the attachment to OSX as a platform, but if I was gonna expend the energy to document a thing, I'd hope it goes towards a good cause and isn't just free labor for like the richest corp I can think of from the top of my head.
  - ewjordan 9y ago
    Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux, which nobody plus epsilon uses (except amongst devs). Impact is a big factor in how useful an activity is, even if it's tied to a big company.
    - em3rgent0rdr 9y ago
      > "Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux" From a purely utilitarian perspective: - The same amount of effort spent trying to document will result in more documentation being produced on a free system, since free systems are easier to document. - The same amount of documentation produced will result in more benefit from end users for a free system, because more people will be able to use a free system.
      - 9y ago

CrazyRabbit 9y ago

https://opensource.apple.com/ https://opensource.apple.com/

mdaniel 9y ago
I have a rule that says something isn't truly Open Source unless you can build it, because binary patching is for chumps. Have you tried to build those? There are several projects attempting to do so, and I have yet to experience "download tar, ..., boot that Darwin build in a (qemu|vm)!" for any value of "...".

static_noise 9y ago

When it's documented it cannot be changed as easily, so it's often better to not document everything in detail.

pjc50 9y ago
Then your users find that their own memory of where to find things and how to perform tasks is unreliable. Has the system changed or they forgotten it? You're effectively "gaslighting" your users if you rely on this.
- static_noise 9y ago
  If they rely on you (you being apple here). It's their fault for relying on undocumented interfaces. Consequently, they should stop using your system but they don't.
- nebabyte 9y ago
  Apple gives users APIs at the level they think users should be operating, not system internals. Are we seriously having this discussion, HN? Did people just wake up today to what their reality has been for years? https://www.youtube.com/watch?v=ilcRS5eUpwk https://www.youtube.com/watch?v=ilcRS5eUpwk
krylon 9y ago
On the contrary, that makes documentation especially important so you can figure out if some changed behavior is a bug, a mistake on the user's side, or intended.
actuallyalys 9y ago
I agree that there's a trade off between detailed documentation and flexibility, but I think regularly leaving out details to allow for frequent changes can be a red flag. Unless your project is new and in beta, you probably shouldn't be changing things that often. After all, even if your documentation is sparse, users are going to start expecting certain behavior just from using your project. You can also tweak this tradeoff a little. If you explain up front that what you're describing changes a lot and don't put it in the official documentation [0], you can be somewhat detailed and still have room to change. [0]: Think a wiki or blog that your project maintains.

deleted 9y ago

[deleted]

jonnguyen12 9y ago

Are we talking about technical documentation or unofficial user manual? We don't need the latter for sure.

quink 9y ago

Why bother? If the people making the thing can't be bothered documenting it you're going to fight an uphill battle. In the long run, for better or for worse, code is documentation. If the code isn't available there'll be only so far you can go. And with the unification of iOS and macOS fast approaching the number of people able to have transparency into even just the POSIX layer is going to drop another order of magnitude. macOS is dead, Apple just hasn't told anyone about it yet. And iOS 11 is going to be it's murderer. If you have the time to document, you might as well spend the time documenting Windows, BSD or Linux; Blink or Servo. Or the JS ecosystem. The Apple specific SMB implementation or APFS or Cocoa are not worth documenting any more than OOXML would be - only as a specification that one party has the power to change and to implement. There is no way for the documentation to be considered prescriptive rather than descriptive for anyone touching the code. It might be useful in some limited aspect for a limited time, but it will decay as Apple considers every single pixel their OS is going to render to be under their control in some way. Apart from what they can sandbox, which amounts to the web platform, which is plenty documented already. > launchd – second only in importance to the kernel – controlled and orchestrated most of the services supplied in macOS Who cares about the launch facilities in macOS when anyone who should care about launch facilities is going to be using Windows Server, Linux or BSD? Apple couldn't have been saying fuck off to anyone wanting to screw around with CUPS or Samba or launchd more loudly unless they shouted it from all the rooftops in Cupertino. > Magic Trackpad 2, never knew how to launch an app from the Dock, or couldn’t manage their Photos library. 1. It'll stop working (here we go, top result for a Google search: https://support.apple.com/en-us/HT204621 https://support.apple.com/en-us/HT204621) 2. Launchpad exists and has a keyboard shortcut and 3. Photos manage themselves. What does manage even mean in the context of you take a picture with a phone, it adds geotagging and a time and that's it. What more do 99% of users want?

enqk 9y ago

This problem is actually the reason I've fallen out of love with Macos as a platform for my home computers. There's way too much stuff that goes around, daemons that are waking up at any given point and doing a lot of I/O, for which there's absolutely no documentation whatsoever. It kills the performance on my old Macs and also doesn't inspire confidence that I'm a user/owner of the device.

nebabyte 9y ago
> and also doesn't inspire confidence that I'm a user/owner of the device ...What gave you that delusion? Are you one of those people who clicks "okay" to EULAs without reading them?
- kronos29296 9y ago
  Actually you still own the device just not the stuff making it actually useful. That is still owned by apple. (EULA)

vladdanilov 9y ago

Apple's primary focus and the source of money is iOS. That is why macOS has to be 1) just noticeably better than competitors 2) inconvenient enough for average users to partially migrate to iOS.

gogopuppygogo 9y ago

This is Apple we are talking about. If you built a knowledge-base like this on your own time and for the right reasons I bet they send a DMCA.

bcook 9y ago
>If you built a knowledge-base like this on your own time and for the right reasons I bet they send a DMCA. Why do you say that? Your post makes me think I'm ignorant of Apple's past litigation.
Walf 9y ago
I doubt it. What claim would they have over a non-fiction work they had no hand in creating? They could sue for other reasons but the judge would have to be a fucking idiot to do anything other than order Apple to pay court costs. How much software documentation has been written by third parties?

LeoPanthera 9y ago

Just in case no-one read the leaflets that came with their new Mac, Apple has fairly comprehensive macOS documentation online: https://support.apple.com/macos https://support.apple.com/macos A lot of this is built into your Mac also, at Help > Mac Help in the Finder. For those who prefer physical books, I've always found the "Missing Manual" series to be excellent.

pfranz 9y ago
How come I never see them come up in Google searches? I have seen it come up when looking for conditioning your battery or the shortcut keys for Target Disk Mode. But more often I'll search for a runaway process name or an OS message that is spamming Console. The top results are Apple Discussion posts that go on for pages, but often don't have a clear result. I also recently was trying to learn more about macOS' init system and got lost like the article mentioned.
- extra88 9y ago
  For the processes, it's not that the documentation doesn't exist, it's that they're very low-ranked in search results (and many who know that they're looking for a process name know to try 'man foo' before a web search) [0]. Any documentation rarely describes exactly a problem someone is experiencing but a discussion forum might, so those are the links that come up first in a search. As for message in logs, I don't tend to find those in other *nix documentation either. [0] https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man8/mdworker.8.html https://developer.apple.com/legacy/library/documentation/Dar...
nottorp 9y ago
Do they? I don't think the OP (or me, for that matter) is looking for documentation telling him where to click in the UI. The article seems to be about more low level stuff.

dredmorbius 9y ago

I hope the author of this site is proud of their fixed-position page header. Because it takes up fully 1/4 of the screen height in my browser. Just sayin'.

zalmoxes 9y ago

If you haven't already, join the MacAdmins Slack. https://macadmins.herokuapp.com https://macadmins.herokuapp.com It's an open-invite slack team with over 12000 users - sysadmins, MDM developers, security researchers and so on. We have various ongoing efforts to document and improve the macOS experience for users. If you have a macOS question, you'll likely find the answer there.

mdaniel 9y ago
> you'll likely find the answer there Well, I hope the Google Bot (plus whichever one DDG uses) also has an invite to that proprietary, closed, messaging system, or that the "macadmins" owner has set up a channel mirroring system ala IRC web logs, otherwise the system you described isn't contributing to the open body of knowledge. Related, although mildly off topic, :fu: slack search

natch 9y ago

To the author, did you file radars listing specifics of which areas you need documented? https://bugreport.apple.com https://bugreport.apple.com isn't just for bugs.

stuntkite 9y ago

OT a bit but I think still related. 8 years ago when I switch to OSX I was furious with finder. Tiny window, no hierarchical browsing and the search just doesn't do shit that is useful. I normally default to locate or find now so much that I was using it the other day I was reminded about how much it sucked. It's literally identical (aside from tags and labels) to what it was forever ago and is a terrible paradigm. I looked around for a bit for some help on refining the search sensibly and nothing in the OS helped (back on topic!). I've been using a great replacement for Finder called PathFinder that does everything Finder should do, but you can't swap it out. All the native places I access Finder are important inroads. They used to have instructions to hack it but apple shut them down. I feel more and more like UI and usability innovation totally ate itself and died at maybe a specific moment in time ~6 years ago. Where did the people and companies go that do cool new things? Are the giants on their laurels long enough yet to get eaten? I'd switch totally to Ubuntu or Mint for my desktop work, but I do things that require the adobe suite, I need a trackpad that works as well as the mac one without fighting it, and I want to just solve problems, not fiddle with barely supported gizmos for weeks. Did we reach the absolute end of all we can do with this juggling of rectangles that display and accept text and now we just get everything that matters to a power user stripped off for the sake of what "most users care about"? I really don't think we have. I'm still pissed and I still have no answers. My kingdom for a $3000 laptop that "Just works" and helps me murder code, deployment, graphic arts, music, and still loads HBONow.

pampa 9y ago
A beefy windows workstation or laptop to cover Adobe & DAWs + VMWare for Linux. With fullscreen VMWare and open-vm-tools I can barely notice that it doesn't run bare metal, and i can keep different distros at hand for different purposes.
- stuntkite 9y ago
  I bought Windows 10 Pro last year and had really high hopes for it after the Ubuntu shim was introduced. Windows is a fucking nightmare for anything involving producing audio at a pro level. The Ubuntu shim does not solve what I need even though it's a nice add. The real kicker is that STILL many errors produce a window where I can't even fucking copy the output. Why that is still a feature, I have no idea. That coupled with how they manage fixes/updates and a general distrust for the system being close to secure... It just didn't work out. I wanted to buy that giant drafting table computer with the knob and say fuck it to the MBP. I went to look at it and bought another kinect one day, and what felt like an omen, their windows run point of sale system that tries to hide in the desks like the apple store failed so bad at taking my card that the guy had to use two different work stations and literally was "turning it off and on again" with both his card swiping windows mobile phone and the computers. I feel like my future is in some sort of hand rolled main LXD or CoreOS or the like, that quickly composts whole systems locally and in the cloud but also easily remote desktops to local Mac and Windows machines. I have ideas in my head and a bit in code for a bare bones graphical interface that renders a graph that I can attach arbitrary points to that go to systems, API, terminal instances, containers, etc. I can weight the node connections and also record weight on paths based on frequency of traversal enabling automatic access shortcuts. Of course OSX is close to impossible to run virtualized, which is stupid as hell. Actually if it could without a larger time investment than my full time job that might solve all of my problems. I don't know, I still need all of the systems that are out there... but I think it's time to put a top layer interface on it that gives me them and more. Setting up a springboard for something that doesn't sit around waiting for big providers to bless me with mana from heaven while they wave their dicks in my face. Here's an example of a nerfed version of what I'm talking about as an OS supervisor UI that I'm using for a lesson series on Docker [https://www.dropbox.com/s/be4lh1015y305jr https://www.dropbox.com/s/be4lh1015y305jr]. There is nothing about it that's clean or safe to operate, but I just wanted to prove it. In the current version you can select a node and drop to a terminal inside of a container. Also, I've added support for API nodes auto generated from graphql and REST (if you write the schema). I think it proves the concept. The next step is the pullback to whole systems I guess.

aurelien 9y ago

Read the FreeBSD documentation ... you'll get it ;-)

schappim 9y ago

>> "I am also daily reminded of Apple’s wholesale failure to provide consistent and complete documentation of its flagship product." The author of this article fails to realise that the Mac is not Apple's flagship product anymore...

walterbell 9y ago

Open-source documentation (PRs requested!) on macOS security & privacy: http://www.oss.io/p/drduh/OS-X-Security-and-Privacy-Guide http://www.oss.io/p/drduh/OS-X-Security-and-Privacy-Guide "... a collection of thoughts on securing a modern Apple Mac computer using macOS (formerly OS X) 10.12 "Sierra", as well as steps to improving online privacy. This guide is targeted to “power users” who wish to adopt enterprise-standard security, but is also suitable for novice users with an interest in improving their privacy and security on a Mac."

phatbyte 9y ago
This is a great resource. A lot of things I didn't even know.

sigjuice 9y ago

How can outsiders even begin to effectively maintain documentation for obscure macOS things like DAS and CTS? I can't be the only person who has never heard of these before.

SwellJoe 9y ago

When I did some work on porting out product to macOS (so developers could run their server environment locally, though a few loons wanted to actually run macOS on servers), I was immediately struck by how awful and incomplete the documentation was. And, I've been working in the Linux world for a couple decades...where docs are copious but wrong about 50% of the time. In particular, the service launcher (launchd, mentioned in the article), and various other system level things (including logs, also mentioned in the article), have so little official documentation as to be laughable. You just have to spelunk the web to find someone who has the tribal knowledge and has shared it in some form. I gave up on the task, as the level of pain was far too high. But, I'm kinda baffled why anyone would volunteer to provide free labor to one of the largest and most profitable companies in the world. I give away tons of my time for OSS, but I'm not about to get out and push if I've paid for a luxury car. I'd rather put my time into something that is free and open for everyone, including my future self. Actually, the word "rather" isn't strong enough: I would never give my labor to an $820B corporation.

igravious 9y ago
> But, I'm kinda baffled why anyone would volunteer to provide free labor to one of the largest and most profitable companies in the world. I give away tons of my time for OSS, but I'm not about to get out and push if I've paid for a luxury car. > I'd rather put my time into something that is free and open for everyone, including my future self. Actually, the word "rather" isn't strong enough: I would never give my labor to an $820B corporation. That's exactly what springs to mind. Why should we do Apple's work for them when they are swimming in cash reserves. It beggars belief that anyone would suggest this. Obviously their pain is so great, they're so tightly shackled, their alternatives so limited, that they would rather willingly donate their labor to a wealthy corporation than attempt to take said corporation to task or shock horror jump ship.
- captainmuon 9y ago
  It's not Apple's work to do. It's not in their interest to document everything. What applies to internal APIs applies to lesser extent to the detailed workings of the OS, like the init system, themeing, etc.. If it is documented, people will depend on it, or write low-level tweaking tools that Apple doesn't want to exist. What is good for customers and developers might not be good for Apple, and vice versa. (A separate issue are the user docs, e.g. how to use Finder. I guess they are good enough, I haven't found the need for such docs.)

nebabyte 9y ago

> We That would be Apple's job, and if you're waiting for them to make it easier for third parties to work on the system they think rightfully are theirs alone to develop, don't hold your breath. Did we all start taking amnesia pills or something? You knew what you signed up for.

seba_dos1 9y ago

No. It's Apple who needs to do that. This isn't a free software project - lack of documentation is an argument for abandoning the platform, not for starting a community project of doing work for Apple for free.

pebers 9y ago
I guess the problem is that Apple don't need to do it; lots of people would like them to do it, and maybe they should do it, but it's not hurting their bottom line much so they can just continue as they are. Unless a whole heap of customers suddenly decide to buy different laptops instead over it, but I'd not be betting on that.
- hobarrera 9y ago
  Arguably, this might happen in the long run. They might slowly lose dev over the years if they neglect documentation, which will eventually hurt the app ecosystem. Eventually, that'd affect user. Very hard to say if the problem is serious enough yet though.
dethos 9y ago
Indeed, the responsibility belongs to the company that is providing the proprietary software/product. Otherwise it would send the message that good documentation shouldn't be provided because the "community" will handle it for free.

yannovitch 9y ago

There is a saying in French which says that half of the treatment to get better is to recognize/admit you're sick . There is an other saying which says "Faute avouée est à moitié pardonnée" (If you admit a flaw/mistake, you're already half the way through forgiveness). That to say that maybe there is a lack of documentation because Apple would have to admit to itself (...and to the world) that macOS is not the absolutely perfect OS without any flaws, virus/malware, or room for improvement, that they want all of us to believe.

sd8dgf8ds8g8dsg 9y ago
> There is a saying in French which says that half of the treatment to get better is to recognize/admit you're sick I believe this comes from the 12 step program of the Alcohol Anonymous (religious sect). 1. We admitted we were powerless over our addiction - that our lives had become unmanageable.

st3fan 9y ago

Launchd documentation: https://developer.apple.com/library/content/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html https://developer.apple.com/library/content/documentation/Ma... See more documents linked at the bottom of that page.

blablabla123 9y ago
Nice, XML config. I wonder if Apple employees are internally allowed to voice criticism.
- JeremyBanks 9y ago
  Plist files have XML, binary, and JSON-like serialization options, and have been in use for longer than JSON has existed. Any Mac developer will be familiar with them, and have access to multiple APIs for handling them. Of all the things in MacOS to criticize, this is just ignorant.

st3fan 9y ago

End user docs about The Dock: https://support.apple.com/en-ca/HT201730 https://support.apple.com/en-ca/HT201730 More links at the bottom

st3fan 9y ago

How to charge you Magic Trackpad: https://support.apple.com/en-us/HT205160 https://support.apple.com/en-us/HT205160 Also included in paper documentation in the box.

jsz0 9y ago
There's also a low battery notification that says something like 'plugin a Lighting cable to charge'

jalcazar 9y ago

"We"?? Maybe we as customers of Apple should demand Apple to better document macOS. Apple can well afford to get the documentation fixed.

extra88 9y ago

The author seems confused. Launchd is a service for starting processes (on boot, on other events, or on a schedule), Centralized Task Scheduling (CTS) is a low-level API used only by developers writing native code to perform tasks within a process [0]. CTS can only be used by a running process while launchd is a running process you can instruct by loading .plist files (normally they're only loaded at boot from LaunchAgent/ and LaunchDaemon/ directories). [0] https://developer.apple.com/library/content/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/DiscretionaryTasks.html https://developer.apple.com/library/content/documentation/Pe...

cptskippy 9y ago

For all the things that Microsoft takes flak about, this is one of the few areas you really can't complain much about. They maintain detailed versions documentation and make it easy to explore. Every so often I come across something that isn't documented well or at all and it hurts. But it has a page at least and on every page they have a public feedback mechanism.

diego_moita 9y ago
Not only that but also tooling (Visual Studio) and community development(Codeplex, Codeproject). The Android ecosystem is not bad, also.

charlesism 9y ago

> I don’t know how many technical authors were employed > by Apple at that time, but I suspect it was a > far higher proportion of total staff than it is now. Or maybe the proportion is the same, but Tim's shorter release cycle has resulted in the OS permanently being in a state of churn.

userbinator 9y ago

Apple has always been vague and stingy with the documentation; despite the author mentioning this, In the days of classic Mac OS, when print publishing was growing as a result of Macs, Apple published an exemplary series of books under the banner Inside Macintosh I have read the Inside Macintosh books but they still felt somewhat incomplete and superficial (although they're definitely a little prettier) compared to what I'd consider close to a "gold standard" for documentation, the IBM PC/AT Technical Reference and the same one for MS/PC-DOS. I suppose it had a lot to do with the general attitude of Apple's culture, summarised in the famous phrase "it just works". The notion that systems should be designed to be so easy to use and obvious as to require no documentation, has resulted in a lack of documentation even for those cases which are not easy to use nor obvious.

pvg 9y ago
I have read the Inside Macintosh books but they still felt somewhat incomplete and superficial (although they're definitely a little prettier) compared to what I'd consider close to a "gold standard" for documentation, the IBM PC/AT Technical Reference and the same one for MS/PC-DOS. One of these is a foot of big books documenting a GUI system and its components, the other is a single volume that tells you handy things like 'The PC/AT has three programmable timers'. I don't think the documentation was ever complete but Apple did produce a lot more of it and had a lot more to document to begin with. The level of documentation is not really directly comparable let alone a symptom of some non-existent 'just works' culture and attitude. If anything, one could make a reasonable argument Apple of the time spent too much effort on beautifully documenting piles of things that were ultimately not useful or successful.

Gracana 9y ago

Does anyone remember "Inside Macintosh," the manuals Apple published back in the classic Mac OS days? I have many of those books, covering everything from how the hardware handles drawing to the screen, up through memory management, files, networking, etc. They're examples of some of the best technical documentation I've ever encountered. It's too bad they don't prioritize that anymore. :(

scott_karana 9y ago
I remember reading about them in the second paragraph of the article... ;-)
- Gracana 9y ago
  S'not the same to read about it. If you're interested in documentation writing I recommend looking for some of Apple's older stuff on archive.org to see what it's like. I don't see much documentation written in their kind-of extended style these days... A lot of documentation seems to be either terse or tutorial-y, there's not much that tries to focus on the concepts relating to / the purpose of a given feature.

e28eta 9y ago

It's old (circa 2006) and really low level, but I loved reading through Mac OS X Internals (http://www.osxbook.com http://www.osxbook.com) If it were updated, or a vol2 was released with all the new stuff, I would immediately buy it. It's not going to teach you how to use Finder, but you'll have a great understanding of the internals.

qualitytime 9y ago

No we don't have to. Stop consuming proprietary code from for-profit corporations.

dman 9y ago

I just wish apple would stop breaking gdb every release. They need to make up their mind on whether OS X is a general purpose OS intended for developer use or if its just a locked down version of iOS which runs on larger devices.

pjmlp 9y ago
It intended for OS X and iOS developers, which use the official supported debugger, lldb.
- dman 9y ago
  In other words writing systems software for OS X if you are not employed by Apple is a fools errand?
  - pjmlp 9y ago
    No, a fools errand is to buy a Mac and use GNU/Linux tooling instead of the official OS X SDK tooling. GDB stop being part of the official modern SDKs quite long time ago.
    - dman 9y ago
      I understand that gdb is not part of the official SDK. I would expect an OS in widespread use to not break userspace and when it does, take substantial remedial action to fix / patch widely used applications.
      - pjmlp 9y ago
        The onus is on gdb developers to keep up with the OS API changes, not the other way around.
        dman 9y ago
        If the changes are well documented and communicated ahead of time, then sure I agree with you. Am also curious now what Apple uses to run cloud services - ie do they use OSX as a server operating system themselves.

doubleshame 9y ago

Here are some docs http://images.apple.com/server/docs/Command_Line.pdf http://images.apple.com/server/docs/Command_Line.pdf https://www.apple.com/jp/server/pdfs/Mac_OS_X_Server_v10.2.pdf https://www.apple.com/jp/server/pdfs/Mac_OS_X_Server_v10.2.p...

unicornporn 9y ago

> I am also daily reminded of Apple’s wholesale failure to provide consistent and complete documentation of its flagship product. Well, I'd argue macOS is not their flagship product. Apple makes their money from selling phones these days. I think they have better things to do than to document a marginalized OS.

Joeri 9y ago

The most profitable software company ever still can't build software properly (meaning: fully documented). Does this mean that it is impossible to build software properly at scale? Or is it just that you don't become that profitable without cutting a few corners? (In my original comment I said "most profitable company", but it seems the dutch east india company gave them a run for their money. So, good news for apple, they still have room to grow.)

topbagsvk 9y ago

MacOS users don't need to document macOS as a volunteer project. http://www.bagswalletsit.com/hermes/scarves.html http://www.bagswalletsit.com/hermes/scarves.html