Hacker News new | past | comments | ask | show | jobs | submit login
We need to document macOS (eclecticlight.co)
245 points by fern12 on Aug 13, 2017 | hide | past | web | favorite | 257 comments

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.

> 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.

Somewhat related, it has become Apple user/developer etiquette not to mention bugs without filing a bug report on Apple's closed issue tracker beforehand:


I can't believe how many hours I've wasted on detailed bug reports only for them to be closed as a duplicate, or "works as expected".

If you are frustrated with Apple, there is only one thing that works: 1) be influential, 2) complain publicly. If you want macOS to be documented, don't do it yourself. Find people at prominent media outlets and start the meme that Apple's documentation sucks, and that it matters for <reasons>. Add all sorts of pressure and with any luck, Apple will address this issue to turn the narrative around in its favour.

Since I don't have any of that power, I try to find open source projects that affect me and donate time or money to them instead.

The big difference is that while bugs can only be fixed from the inside, the documentation can be greatly improved even without Apple’s buy-in.

Not efficiently. And others volunteering their time to reverse engineer documentation on an ever moving target sounds like an exercise in folly.

Especially when the first party could hire technical writers for a fraction of the cost of developers and make this problem disappear.

They could solve the problem, but they are not doing it. Trying to force their hand by public shaming may work, but I don’t think it will. Volunteering the effort seems like a pragmatic approach. I would love to have a place where I could send a PR to fix a documentation shortcoming. Adding requests to Radar is futile.

That's not pragmatic, that's just... wrong, on so many levels. Either 1) shame them, 2) move to OSS, or 3) suffer, but please don't donate your precious time to solve the problems of a rich company who doesn't care about its users. Doing so would only diminish the effect of first option (shaming) and is just not fair to anyone.

Or, write a complete reference book and sell it for profit.

You could say the same thing about many free software projects created for the ecosystem. Many of them could have been created by Apple and shipped as a part of the system. I have donated my precious time to solve problems that should have been solved by Apple before. I’m not extatic about it, but my itch got scratched and hopefully I may have helped other people, too, so I consider it a pragmatic improvement. I can see your point, though, so let’s simply disagree, it’s good for the world to have different people try different approaches.

Yes, and it's a good reason to pause before making new free software for a nonfree system.

Sometimes it is good because it helps people use more free software- but not always. Sometimes it just helps people use the non-free software.

I think the difference is that those weren't created solely for Apple's benefit.

Which projects do you have in mind? Only one that comes to mind for me is Homebrew.

  1) be influential, 2) complain publicly
3) don't buy their products.

Imagine you have written a small utility for a commercial OS. Something like it should have been included with the os but wasn't.

You've scratched your itch. You decide to open-source it, so that everyone else who has a similar problem could benefit. Kudos!

Good thing is that you can push it to Github or something like that, making it instantly available.

Now replace the code with documentation. You have found something hard to find and important. You've solved your problem. Now you can share it, so that fellow developers could benefit from it. You have already spent time on it, for your own purposes. You don't want to document the rest of the lacunae in the official docs, but this particular bit is ready.

You'd like to waste as little effort doing that as possible, and make it instantly findable.

Where do you go?

Hence the idea of the original post.

> Where do you go?

Typically I just leave it in the code so that people aren't confused by non-obvious code. When I'm dealing with an API and the documentation is poor, I usually just search the name of the function on GitHub, and see how other people prod it.

Will you make a PR to just update someone's code comments? How searchable would it be?

It's sad that stackoverflow documentation project is being sunsetted, but it was probably too ambitious a project. The original post suggest something much smaller.

> 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.

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.)

If the experience of developing for the OS is terrible because the documentation is terrible, well...an operating system without a thriving application ecosystem is an operating system that is not long for this world. No matter how good the OS may be. Computing history is littered with the corpses of better operating systems (Amiga and BeOS and every UNIX other than Linux come to mind) that didn't have the app ecosystem to keep them alive.

Obviously, Apple isn't hurting, but it can take a long time for anyone to notice that a huge tree is rotten in the middle. I don't know if that's true of Apple; they've been pretty successful in the transition to mobile, and their iOS ecosystem seems very healthy, but, if the terrible docs are a company-wide issue, it might be a slow-moving disaster. Docs are unsexy enough to where I could believe Apple would completely fuck them up, just because nobody wants to work on the unsexy stuff and nobody thinks about it when things are going so well for the company.

I'm just being charitable and assuming Apple knows what it is doing - e.g. assuming "malice" instead of stupidity.

For example, macOS is themeable under the hood. Nearly all Cocoa controls are defined as vector graphics in an "art file", rather than hardcoded in the library. This was probably not done with themability in mind, but is just a side effect of good engineering. I bet there was a meeting where the engineers said "we have this great feature where we can change the theme of all Cocoa apps", and it was decided to not expose that feature for reasons like "brand recognition" and having all macs look alike for support reasons. I'm pretty confident that happened because Microsoft did the same and locked down themes with Windows XP (and somebody stated their reasoning), and also the GNOME project removed theming from the main UI and crammed it into a scary "tweak" tool (one dev said basically that theming is not a desired feature for them).

Similar logic applies to other things, like the kernel interface.

I fully understand why they come to such decisions - but I as a user and developer (and interested in "hacky" things) would love these things to be documented.

I don't think the status it is hurting their bottom-line, or the quality of mac apps (yet). Cocoa stuff seems to be documented decently enough. But I agree, they have to be careful if they don't want to fall behind.

AmigaOS is more of a zombie - it's still being developed, and has spawned at least two "offspring" in MorphOS and AROS that are both still developed (and ported to new hardware in the case of AROS in particular).

And AmigaOS was a shining beacon of efficiently surfacing apps online early on. Aminet [1] provided a robust mirror system and ability to browse a big catalog (still online and updated) of downloadable AmigaOS software. It was a large part in letting AmigaOS remain viable for users much longer than it otherwise would have for most.

[1] http://aminet.net/

Sure, and I used my Amiga until well after CBM died; I didn't switch to a Windows PC until after Windows 95 came out (and then switched to Linux soon after). But, it's hard to argue that the smaller application ecosystem didn't hurt it. There were good applications for most tasks, but the big names were absent, and businesses rarely chose Amiga for that reason (and a few other reasons).

I agree about that - didn't mean to imply otherwise. Though it also quickly got expensive (I'd argue that for a while in the mid 80's it was cheap as a PC alternative - my dads PC was slower than my Amiga 500, had no graphics abilities, had less memory - it's two benefits were a 20MB harddrive and compatibility with PC apps; for that he paid about a $3000 premium).

In fact, part of the point I didn't put across very clearly is that things like Aminet demonstrates how important that ecosystem is. Amiga would have become useless to most users far earlier if we didn't have incredibly well curated sets of applications, and amazing dedication to maintenance (e.g. even today people are releasing their own bug-fixed versions of system libraries and the like) - it took a lot of effort to try to compensate, and it still wasn't enough.

This only follows if Apple indeed wants to kill macOS.

If they want users... then you kind of need to have even low level documentation. Because the kind of serious apps and third party feature adds that make an OS bearable to use depend on them.

Of course they want to kill macOS, it's only a small fraction of their profits. They've rewritten all the software they've acquired over the years, Final Cut Pro etc, I'd bet they're internally compatible with whatever their future iOS based desktop OS is.

It's a $25B+ a year business that earns more profits than all the other PC makers in the world combined. I'm pretty sure they don't want to kill macOS.

Not saying they want to kill Macs, just move them to a new OS so they can share developers with the 10x larger iOS market.

If you have 50% of your OS programmers working on an OS that only 10% of your users use, seems like a waste

But macOS and iOS share enormous amounts of code, if not the majority. The kernel is pretty much the same. APIs usually get support on both systems, with the exception being the UI layer.

Indeed, if they have different APIs on the 2 platforms for the same functionality, you can probably bet that pretty soon one will be ported across to the other and the other obsoleted. Recent examples: PDFs, Bluetooth, Media SDKs (AV Foundation etc).

> 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.

YES! MacOS users don't need to document macOS as a volunteer project, they need to demand Apple to give them their money's worth.

And yet Apple does not contribute to homebrew at all. The one project that makes osx usable for developers.

I used OS X a few times for iOS development, never used homebrew. Am I not a developer?

Maybe you had different requirements than other developers. Or maybe you've got a lower bar for considering something "usable".

My requirements were those that any OS X and iOS developer have, which don't require UNIX CLI rather XCode tooling, and are happy to use any UNIX certified POSIX system for the occasional CLI automation of OS X and iOS development.

Now those that bought OS X as a pretty alternative to GNU/Linux and *BSD, for development that should actually be done on those systems, might miss something like homebrew.

Apparently only those are developers on HN speak.

Interesting definitions. Theirs excludes you as an OSX developer, and yours excludes them as OSX developers. How about: Your requirements weren't those of "any OS X and iOS developer", unless you apply a "no true Scotsman" argument. Similarly, a nicer CLI environment is only applicable to some styles of dev on OSX.

OS X is a certified UNIX, no need for external tooling.

Except for all the tooling that people like to use that isn't covered under Unix certification, of course. It's not like the Open Group is the ultimate arbiter of useful software on Unix-like systems.

iirc, they actually contacted Max Howell (creator of homebrew) and got his input on how to make command line tools work better for developers and homebrew specifically.

Assuming this happened and lead to anything it is still far from actually supporting it.

IIRC Max now works at Apple and is responsible for Swift's package manager.

I think he left sometime last year https://changelog.com/podcast/232 they start talking about his departure from Apple at 55 min and 26s, unless he went back recently


They did contribute to Macports which does the same.

> 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.

God launchd's documentation is so woefully incomplete it's soul-crushing, even more so as they deprecate "legacy" subcommand (which are "community documented" as various souls tried to understand how to make them work) and the documentation for the "replacements" is even worse. I'm not a sysadmin, I don't really care for launchd, but every time I want to set up a cron I waste an hour trying to coerce it into doing something useful before just falling back onto crontab.

Not to mention the… idiosyncratic command lines which makes even documented tools a chore to use fucking `lipo`:

    lipo  [-info]  [-detailed_info]  [-arch arch_type input_file] ...  [ input_file] ...  [-arch_blank arch_type] [-create] [-thin arch_type] [-replace arch_type filename] ...  [-remove arch_type] ...  [-extract arch_type] ...  [-extract_family arch_type] ...  [-verify_arch arch_type ...]  [-output output_file] [-segalign arch_type value] ...
the various options are mostly exclusive which is documented but weird as fuck, but then say you want to check if a given binary contains a specific arch

    -verify_arch arch_type …
         Take one input file and verify the specified arch_types are 
         present in the file.  If so then exit with a status of 0 
         else exit with a status of 1.
You'd expect `lipo -verify_arch x86_64 <file>`, but no, since it can take multiple arch rather than repeat -verify_arch you must put it at the tail: `lipo <file> -verify_arch x86_64`, if you don't you get a screenful of garbage telling you that you gave an incorrect architecture flag, which architecture flags are valid and re-printing the synopsys.

> launchd's documentation is so woefully incomplete it's soul-crushing

Interestingly, systemd (which, AFAIK, is influenced in large parts by launchd) goes the exact opposite way and has amazingly complete and well-structured documentation.

I've found that to be true, as well. Say what you will about systemd, but they've really done a good job documenting it. There are also useful blog posts from some of the developers delving into various topics. Nearly every question I've had about systemd (and I've had a lot, as our products interact with the init system tons) has been answered either by the docs or by a blog post by one of the systemd developers.

e.g. I recently dug into how to build an inetd style (called "socket activation" in systemd) service. I found pretty good core docs, and a very good blog post with real and useful examples.

Learning my way around systemd has just been a good experience, all around. I have my complaints, but doc quality isn't among them.

It's a big project, but having it all come from the same folks does lead to a consistency across sub-systems that is rarely seen in the Linux world.

"I waste an hour trying to coerce it into doing something useful before just falling back onto crontab."

Unfortunately, cron and crontab only function as expected in every other (every third ?) release of OSX.

>And, I've been working in the Linux world for a couple

>decades...where docs are copious but wrong about 50% of the


Nice summary of the status of Linux documentation. Not sure if it's really 50% wrong, especially the man pages make an impression of over-corrected but the usefulness depends on the tool and is completely random. But yeah, online documentation, classical tutorials are usually useless. When I see a tutorial, I close the tab. They just lead to dirty installations. If a tool needs a documentation, there might be an alternative that needs none. ;) But seriously, a lot of stuff on Github is obvious to use.

Not sure about the macOS. Having changed from Linux to macOS as my main (laptop) OS, I first noticed the unusual BSD tools. So I installed GNU tools on my first year OS X. Now I just use the BSD tools, some I even prefer over the GNU versions. But I guess the stuff that has been developed by Apple has no docs at all..

> But yeah, online documentation, classical tutorials are usually useless.

How long ago was this? Checkout the arch linux wiki. It's a pretty great resource for all things GNU/linux.

The Arch wiki is great for dealing with common problems in popular software. Other stuff tends to be about as outdated and incomplete as the average "how to" blog post. It's a good resource to have, but it's not the same thing as having well-documented software.

I would argue that when you're talking about free software, having documentation for common problems in popular software is the only reasonable expectation. Also that many/most of the most popular Linux tools have extensive documentation of their own.

Yes, setting up Linux to book as an EFI stub is a common problem. /s

I used Arch wiki to finally get it figured out, iirc.

I wonder how much this has to do with the code, and coder, churns in the Linux ecosystem.

Seems to me that there is a new weekend plumbing project popping up and being replaced almost monthly, if not even more often.

And it if gets an toehold in the ecosystem, the initial developer will quickly move on as he runs out of features to graft on and thus lose interest.

Then whoever takes over invariably decides the codebase in shit, and start over from scratch. And the cycle repeats.

Well, that might be true of some random special-interest packages; but for base system components like the kernel (linux) and the init system (systemd), you see the opposite of that description. The maintainers of core GNU/Linux infrastructure are, for the most part, permanent and devoted.

Watch systemd get passed off soon enough.

Never mind that calling it a init is a mislabeling at best...

  # man pdftohtml
This manual page documents briefly the pdftohtml command. This manual page was written for the Debian GNU/Linux distribution because the original program does not have a manual page.

That is outdated though, at least my current release version of poppler (0.57.0) has a manpage for pdftohtml which says at the end "This manual page was written by Søren Boll Overgaard <boll@debian.org>, for the Debian GNU/Linux system (but may be used by others).". According to the current poppler PKGBUILD in Extra[0], there are no patches applied.

Edit: Actually, poppler has had the pdftohtml manpage upstream since version 0.5.0, which was released 2006-01-11. The last release of poppler without a pdftohtml manpage was 0.4.0, released on 2005-08-07. How on earth are you running a twelve year old version of poppler? Or does Debian/Ubuntu still overwrite the upstream version of that manpage?

[0]: https://git.archlinux.org/svntogit/packages.git/tree/trunk/P...

Maybe Debian forgot to remove their patch when the manpage was upstreamed?

> 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.

I've filed documentation bugs against launchd. They acknowledged the issue, and then filed them for resolution in the n+2 major release in macOS, because it was too late for the next major release.

I suspect their technical documentation process to have gone pear-shaped.

Recently had to standup an OGS cluster for mac os sierra. Took me a day to get it built and deployed where it takes 15 minutes with any Linux I know of.

The worst three years I've recently experienced was supporting a dual OS (linux and mac) build/deploy for a highly complex proprietary scientific modeling system.

Maybe the project can get started, add some donation links, and someone from Apple will help them out (with info or docs).

Management probably doesn't even realize this is an issue. Perhaps getting this started will get some visibility on the problem.

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.

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.

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.

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.

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.

Ugh, finder is shit. I've set my default to list view a million times only to see a bunch of folder icons on my screen everytime I double click a directory.

I enjoy living in terminal. I'm very mediocre with both find and grep but I'm getting better and it makes me feel cool ;-), heh.

FWIW, I've never had that issue. Are you aware it sets the view type for each folder? It makes sense if you want to view different files in different ways. If you want to set all views to list system wide, you can set list as default in the view menu. Depending how you've set other folders you may need to nuke view settings, by it sounds like that won't be an issue for you. Spend a minute to learn how your tools work man. https://howchoo.com/g/mzuxyjqyzmy/how-to-set-the-view-option...

With textexpander, grep, sed, awk, and xargs I macro my way around most of the issues. If you haven't tried TE I highly recommend it. I found it when I started to suffer from some repetitive strain injuries that look like carpal tunnel last year. Being hobbled has actually improved my output!

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.

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]. 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.

> 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.

BTW a standard way to do it is to just press Ctrl+C in such window without any text selection or context menu. Because such messages could be shown when system has no resources to create context menu or text selection, and that was very important in 16-bit days.

Let me klingon to the thread with this:

It's 2017 and I still can't use the keyboard to copy and paste from and to a Windows command line window...

Yes you can. Try it out.

Windows has better keyboard accessibility than any other desktop OS.

Ctrl C and Ctrl V works in Windows 10 command prompt.

Also if you're not quite ready to kill yourself while using the windows command prompt. Enjoy a powershell.

You'd probably enjoy Cmder[1]. Everything works really nicely, it supports multiple tabs, and you can download a version that includes most of the Unix commands you know and love.

[1] http://cmder.net/

> you can download a version that includes most of the Unix commands you know and love

Is it the actual Unix commands that I actually know and love, or just 25-year-old parodies like on macOS? (I've stopped keeping track of how often my bash scripts broke on macOS because I was giving some switch to a coreutil that was introduced less than 25 years ago.)

Alt+Space E P

I'm sure your right. The fact that they haven't updated that and I've been in *nix/OSX for 8 years now made my frustration point maybe lower than it should have been. Then the next thing I'm doing is trying to use cmd and powershell and my hair falls out.

But this is great info and will definitely keep be from cursing quite as much next time I'm MS admining.

I hear you about the audio part. I do electronic music as a hobby - I'm not much of a keyboard player, but I do a lot of editing and tweaking using a digital audio workstation program (DAW).

Whenever I look for stuff in user forums, it seems like it's always the folks on Windows who are having a devil of a time getting audio drivers and stuff to play nice. I can't imagine dealing with all of the nagware popups and such on Windows, either, when trying to run a song. Sounds like the kiss of death if you were ever performing.

I have been using Linux since 1995, but switched over to OSX (Macs) about 5 years ago. Commercial audio products generally don't work on Linux. Maybe you can get Reaper to work under WINE, but good luck getting any licensed soft-synths to run (maybe, but I never tried). I'm sure you can "muzzle" some of Windows more annoying nagging and such, but I have other things to do than get an MSCE cert - paying triple for a laptop to Apple every 5 years or so turns out to be cheaper and faster than keeping up with MS internals :-(

Back to the main topic: I've developed a vested interest in the last few years of seeing OSX continue to thrive. I hope Apple doesn't kill it by continuing to make reckless changes to the hardware and/or software.

FWIW, Ubuntu Studio rocks for audio guys.

It probably depends on a personal workflow, but for me, Finder works perfectly, and I really miss it on Linux. I have a reasonably organized directory structure, and I navigate and do basic tasks like copying mostly using just a keyboard. I remember directory names and I just start typing their names and the Finder goes to them (actually, most file managers have this feature). Occasionally, I do 'ls | grep' or 'find' from the console to find some specific stuff (I have Spotlight disabled).

I agree. Years ago Finder left much to be desired, but with all the updates of the last few revisions I'm not left wanting for anything.

People complaining about searching likely haven't tried smart searches, it's awesome.

Can anyone specifically call out what their issues are with Finder besides "it sucks"? I really feel that I'm missing something here.

I have not used smart searches, and now I'm reading about them and it does look pretty cool. But that search bar should give me something sort of close to what I'm looking for in a couple strokes and it really doesn't.

I can specifically call out what my issues are with Finder.

- Where is my fucking folder tree. There was no reason to take it away other than "thinking different" just like the backspace key. Super special guys.

- Search bar does not behave in a way that I think comes close to useful for quick search.

- Why does the window default to something so small and not have an obvious way to set the default spawn size to something reasonable. At this point it should be context aware.

- I don't want more windows, I want tabs too.

- The sliding cell browsing is cumbersome, it sometimes forces you into a folder when you are trying to be in it's parent, it limits your view of your total file list, and in this view there is no way (that I know of) to utilize ordering without the dropdown, so you are stuck with hitting the first letter of the file you think might be there to try to get there quick.

- let me make symlinks from the UI.

- The list view is great for the most part, but since you don't have a tree you have to either loose your browsing context to move to a new folder or you have to open a new window... and it will be too small. Then when you try to drag things into the new window, that probably defaulted to the sliding cell view floating around to get where you want to go will inevitably have you dropping the file somewhere bad. This was the most egregious before Lion when "cut and paste" did not exist. You could enable something that called itself that but it didn't do it and used the trash? Mostly it was just delete.

- I can't preview a file in the list view without hitting space and blocking my view of my context.

- It appears to be designed to keep you away from the system HD. More and more so with every release. I want to look at my filesystem, it it's entirety, easily and without using "go".

- Because you can ONLY use finder for getting files from an application you are stuck with usually a default view that is just a directory dropdown. Then you open it up and it's the slider cell. Then you get trapped and you can't go up a single directory so you have to go to a directory that you used recently, hopefully.... if not you have to go to you user root and navigate down a train.

- If you're gonna be designed to keep normal users "safe" then maybe let me have a button that does "open ssh in directory."

- Drag and drop file copying is laggy as fuck and produces constant problems with relocating files. It's always been the same level of unpredictable and now I'm just trained to sit there and wait for the green +. If the UI is going to be so restrictive and drag copy centric, then this should be like lightning.

- Let me use cli applications from the UI. A right click is fine, a button is ok, a hot key is better. This is a Unix based system. Give me that option, out of the box.

- Without any customization, the program should be focused on less clutter, not more. The defaulting to opening new tiny windows that get left in a stack is bad. I sort of get the DMG open window install process when we were back in the CD days like 12 years ago. Now it's ugly, and shitty, and gives leeway to software providers to just do dumb illegible stuff. It seems that the rendering of the DMG install windows changes over time and that breaks the desired UI for older packages. This thing needs to die.


I want to be able to move down a tree looking at files like the cell does, with filtering, with a tree on the left, with easy file previews, to any place I can write on my system. Maybe that includes downloading a file from Chrome into /opt. File browsing is a noise heavy data intensive problem sometimes. If you are going to arbitrarily make the most basic tool on the system default to an oddly specific size, well then in use you should do some context detection and expand when there's a huge god damned list of files in the folder. I. Should. Always. Be. Able. To. Sort. And. See. My. Sorting. Options.

If any of this is available, please give me protips.

Unfortunately, your points aren't numbered, but I'm confused by a couple of them.

- Finder has had tabs for a few releases, and I can't recall the last time I had multiple Finder windows open at the same time. I use tabs for everything.

- By "sliding cell" do you mean the columns view? I use the list view roughly 100% of the time, so I'm no help there.

- On my system, quicklook opens a preview to the left of the finder window, so it doesn't cover the finder window. I think I must have moved it over there in the past, and it remembers.

- My system shows me every single dotfile, hidden file, and everything. I don't recall which setting I used for that, but zero things are hidden.

- Do you not have right-click, Services, New Terminal Tab at Folder? If not, then that must be something I installed in ages past.

Finder isn't perfect, by any means. It conflicts with how I like to do things semi-regularly. But I think a few of the issues you've raised might be solvable. At least that would lessen your pain a little.

Some of the differences between the defaults and what I see on my system might be down to this: https://github.com/mathiasbynens/dotfiles/blob/master/.macos

For showing "system hidden files", most popular is the ~/Library, run this command in terminal

    defaults write com.apple.Finder AppleShowAllFiles YES
For toggle display of hidden & dot files, type "Shift + Cmd + ."

I can already see how n-gate is going to summarize this thread:

> An internet complains about how macOS documentation is only transmitted by tribal knowledge. Hackernews acknowledges the problem, and proceeds to trade said knowledge in exchange for internet points.

You are not wrong, but my account is throw-away just for this thread. Not hoarding HN points, that is a ridiculous behavior.

Don't worry; I didn't mean to bash on you. I just saw the irony of the thread.

A lot of these just seem like you aren't familiar with the Finder, did you check the menus, preferences, or do a web search for Finder tips?

- No folder tree you are correct. I don't miss it personally. Gotta just deal with this one I think.

- What way specifically does the search not work for you? It's incredibly powerful and you can search by file name, content, file type, creation date, etc.

- It should save the window size you last set it as on a per folder basis when you open a new window from a location. Don't really have any troubles with how it works personally.

- Finder has tabs. Command+T

- Not 100% clear on the problem exactly. If you're going into the wrong folder you don't just have to select a folder by the first character, just keep typing and it will jump to the matching folder name in a list.

- File -> Make Alias

- This one is a bit unclear too. Use spring loaded folders, or a new tab in the location you want to drop to or add the folder to the sidebar that you want to drop files to. Cut and Paste with same named files is a lot better than it used to be and basically works fine now, IMO.

- View -> Show Preview

- Indeed it is designed to keep people away from the system files. 95% of people shouldn't be in there. And of the remaining 1% most of them shouldn't either even if they think otherwise. :P

If you actually need to muck in the system files you can toggle their display in the Finder via a terminal command.

- Command + Up Arrow to go up a directory

- You can open a directory in the terminal easily in a number of ways, including dragging and dropping the folder into the terminal window or icon, using the services menu, etc.

- I don't really find drag and drop copying to be slow in general, are you on a spinning HDD? Anyway with High Sierra the new APFS will make copying files instantaneous.

- There are various services you can use or you can create your own automator services, folder actions etc. to do a multitude of things.

- Finder is decently clutter free IMO, AND it can do a lot of sophisticated things as well.

I'm not GP, but I recently sank time into trying to change Finder searches to default to the current directory instead of my entire machine. It mildly infuriates me that I can't change this; I gave up after I saw com.apple.finder.plist is not plaintext.

Plist files have two standard encodings, an XML-based textual one and a binary one. You can use plutil to convert between the two, e.g.

    plutil -convert xml1 com.apple.Finder.plist
However, for preferences you probably want to use the `defaults` command instead, because IIRC they’re managed by a daemon (cfprefsd) that might not notice if you modify the backing files while it’s running.

When someone decides a config file needs two different serializations and a daemon, I'm reminded of https://www.jwz.org/doc/mailsum.html.

The two different encodings aren't just for config files; property lists are used throughout the OS for all sorts of things. They're a serialization of standard data structures such as arrays and dictionaries: same idea as JSON, decades before JSON. In retrospect, the XML-based text format is excessively verbose, but back then XML was all the hotness… As for the binary format, well, even given JSON's relative succinctness, there are many different formats that attempt to fill the role of 'binary JSON' (BSON, BJSON, JSON-B, MessagePack, CBOR, UBJSON, Fleece, PSON). It's just that none of them have become ubiquitous, probably because of some combination of fragmentation and the lack of built-in browser support.

As for the daemon, among other benefits, it allows preference changes to be immediately visible across all processes on the system, rather than requiring manual action to reload from disk. See:


Default search scope is an option in the Finder's preferences window and has been ever since 10.7...

Thanks for your point for point response mate. I'm going to take a look at all of it.

Sorry for the points that were unclear. They are general frustrations that I've had. This looks like it'll help with a lot!

> - It appears to be designed to keep you away from the system HD. More and more so with every release. I want to look at my filesystem, it it's entirety, easily and without using "go".

One "pro tip" is use "Cmd + Up arrow" to navigate one level above current folder.

Also, Finder creates ".DS_Store" files in each folder, which remembers current folder display. If you want to enforce say "List files" view everywhere, you will also need to nuke these from your system.

There is Path Finder, which is a good software (Shareware) that has a more traditional take on file explorer software, which might be good to check out if you are coming from Windows or Linux.

Myself, I'm just giving Finder a second chance, after having used Path Finder for a couple of years. It is well worth learning some of the key combos for better use.

Here is some more:

In finder, or in a "Open file" dialog, you can type "Shift + Cmd + G" to get a "Go to folder" dialog.

In finder, or in the "Open file" dialog, you can type "Shift + Cmd + ." to toggle "Show hidden files" (.dot files).

Thanks for the pro tips homie! I'm taking this and some of the other responses and making a cheat sheet. You guys have genuinely improved my situation.

You may know this, but from column view you can use the toolbar or a keyboard shortcut to do 'Arrange By', which is not exactly a sort but similar. (It splits files into groups based on intervals of the specified property, and the groups are sorted, but the files aren't sorted within the groups.) Alternately, it's not exactly the most streamlined option, but you can change 'Sort By' from the window that pops up from Cmd-J.

I find Dolphin to have every possible feature I could ever want under Linux, I feel pretty confident in saying that it can be configured to work exactly how you want it to under Linux.

This sentiment is why I do almost everything in a terminal. I see even people who use mac do everything on the terminal. Whenever someone complains about a UI tool crashing, acting wonky, being slow, my reply is always 1. I can't help you, I don't use that; 2. Just use the terminal.

UI fashions come and go, but the terminal is forever.

If you are just using bash for everything why don't you just use a tty instead. Jokes aside, Isn't linux a better idea if Bash is all you need? The only difference is that Mac has more proprietary stuff that don't support linux. If that's not an issue linux is much better.(IMO)

Well, I don't use bash (zsh nowadays) for literally everything. I also use the browser, etc. My VIM isn't in the console, I use the GUI, so I can have more colours and better fonts. But in general, when I can, I control things via the least complicated interface possible - plain text commands.

My gripe isn't that there's anything inherent in GUIs that makes them a less reliable interface than the terminal, it's that getting them to the same level of dependability appears to take more time. And, for all its warts, the fashion du jour of making a GUI by just dumping HTML+JS in a browser instance is something I whole-heartedly support, because it gives application developers probably the simplest (today) wide-spread technology to build GUIs with. It almost always results in applications that consume too much RAM, too much CPU, aren't native-looking, and there are probably other easy GUI-building solutions (QML?), but at the same time they're trivial to edit, quick to write, and there is a ton of documentation and a large community around them. I really hope that electron becomes a standard installable application platform in the near future.

Device drivers. That's what kills Linux for desktop/laptop use.

I much prefer mdfind[1] to locate or find on macOS, it uses the same metadata Spotlight leverages.

1: https://ss64.com/osx/mdfind.html


Listen man, I do plenty of customization. What I'm bitching about here is what I consider to be a lack of innovation and a dereliction on obvious existing, key tools. Finder is a beautiful example of Apple not taking care of it's shit.

I don't need a fucking hand hold. My 3 year old Macbook Air is in my opinion the BEST laptop available. I'm angry that the innovation appears to have ceased from the availible providers and I just can't fathom why.

Just because I used a vernacular you don't appreciate doesn't mean I don't take my work seriously and know how to operate my tools. The second they shape up, someone else delivers me an answer, or I write something to get me out of this platform, there I go. Nothing I'm talking about involved "hand-holding." I want a same priced laptop, with a good GPU, with what I've got now, plus some effort into glaringly obvious old problems. Maybe innovating in a direction that was geared towards a producer and not vibration emojies for a jogging watch. If my math on their income is right both could be possible.

Maybe I'm just naive.

> What I'm bitching about here is what I consider to be a lack of innovation and a dereliction on obvious existing, key tools.

The confusing part is you mentioned PathFinder as being a great alternative yet it's very much a Norton Commander (1986) style file manager that hasn't changed all that much in the last decade. It's a great app but proves almost exactly the opposite point.

I don't think that my point is opposite. I find Finder to be so regressive that just more of the exact same would be a blessing. It's also entirely possible that hierarchical file system browsing is a solved problem and Norton Commander or even XP MS Explorer is as good as it needs to be. I don't entirely buy that it's the final form, but sure I'd be fine if it were true.

My suspicion with Finder is that it was deliberately made small and cumbersome to drive people to Spotlight. However at the time Spotlight was totally inadequate. The iOS platform started to take off and caring about that was shelved. To make up for that I used Alfred for years until Spotlight was updated. Alfred still has a leg up on Spotlight to some degree, like being able to run ssh commands. The Spotlight update came with what? Lion? To just make it pretty good?

How Spotlight works is absolutely indispensable, but that doesn't leave me in a place where my workspace is cleaner and easier to navigate than if they just gave me Norton Commander along with it.

Your delusion that paying "availible [sic] providers" the large price tag they put on their electronics and 'doing plenty of customization' make them "your" tools is the reason I don't take you seriously; "your vernacular" is more an indicator than an issue in that regard.

> The second they shape up, someone else delivers me an answer, or I write something to get me out of this platform, there I go.

The first two are more of the same. The third is just something you're telling me (and yourself?) to try and continue the charade, as anyone capable of taking that option would already (and as I said, did many years ago when they saw the choices in front of them) have done so, and would not be "angry" over what they would see as the obviously financially sensible decision from Apple et al.

Can you elaborate on what technology choices I'm missing? Lets just say specifically the Finder issue. Is the solution to use Linux as my desktop environment? I mean this honestly, I'm not trying to be flip.

Can you give me some examples of the solutions that other people have moved to years ago that you are referencing? I am very open to the fact that I could have just totally missed the train to a better creative tooling experience.

I don't accept the financially sensible part of your argument. I know how that what a company makes is money, and is beholden to investors over all. In my opinion, innovation really stopped around the time the iPhone3 took hold. I personally don't give a shit about their bottom line, it's doing fine and they can totally continue to funnel us in a direction of more of the same. However, I do think leaving the creators they once prized and facilitated behind for a more narrow experience catered to a consumer experience of walled gardens and media subscriptions has currently left the market wide open for a new home for people like me who are begging them to do better.

3 years and no reasonable update to the tool I use to produce my craft and it's still the best thing. That's really saying something for what the company has built as a legacy. The gap is so huge now, and they appear to just keep gutting focus on tools for their once beloved artists and creatives. A new iMac looks pretty good! But it doesn't live up to where I think their platform leadership should be.

In my opinion they have left a desperate, loyal, audience out in the cold so long that it's offensive and I'm looking forward to whoever can fill the role next.

> Lets just say specifically the Finder issue. Is the solution to use Linux as my desktop environment?

Yes, especially with KDE's Dolphin file manager which is more or less the pinnacle of GUI file browser.

See https://www.youtube.com/watch?v=jkWuVCKpiXs

it becomes especially good when you start taping in its scripting capabilities and the wealth of scripts available: https://store.kde.org/browse/cat/102/.

Please be cautious about recommending KDE's Dolphin. According to Hanno Böck in https://media.ccc.de/v/SHA2017-148-improving_security_with_f..., KDE are refusing to sandbox the thumbnail/preview code, which has proven to be riddled with easy-to-find bugs (using software fuzzing)

how do we know there aren't similar bugs with MS explorer / Finder ?

Well, we don't, but would you rather use software known to have bugs or software not known to have bugs?

uh... software whose bugs are known and whose source is accessible of course ? it's not like finder does not have CVEs: https://www.cvedetails.com/vulnerability-list/vendor_id-49/p....

I use `find . | egrep -i foo` to find foo on OS X.

  ~/Downloads$ find . | egrep -i lisp
It works well on an SSD. I also wrote a script called `narrow` which lets you pass in several terms to narrow the results by.

  ~/Downloads$ find . | narrow self pdf
  ./An Efficient Implementation of SELF, a Dynamically-Typed Object-Oriented Language Based on Prototypes.pdf
  ./Optimizing Compiler Technology for SELF, a Dynamically-Typed Object-Oriented Programming Language [].pdf

  ~/Downloads$ find . | narrow racket h$
I know this isn't too helpful of an answer. It isn't responsive to your argument that the GUIs have stagnated. But it's possibly a way to get what you want.

The original poster already said "I normally default to locate or find now...", so presumably he's well aware of find.

So, what point are you trying to make here? That everybody should write their own tools?

That seems like a pretty inefficient use of everybody's time.

Starting a comment with a personal attack isn't well-advised here.

Doing it twice in a row, far less so.

I don't see how wanting a competent file manager or at least have the ability to completely switch to a different one has anything to do with "hilarious entitlement", it seems like a pretty reasonable expectation.

> you can't simultaneously hope for a consumer product that "Just Works^TM" and demand your customization needs

The problem is Finder "doesn't just work" for many people, so yeah, they should be allowed to swap it, that has nothing to do with it "just working' in other parts of the system.

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

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.)

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.

Maybe, sometimes, some of us just want to make a thing we use better rather than attaching grandiose moral judgements to the political status of a piece of fucking code.

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.

> "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.

Not sure that I agree with the second proposition. I'm pretty sure vastly more people choose to use iOS and macOS than free systems.

But more people will choose to use free systems if they get better documentation (that is tailored to average folk, not computer enthusiasts).

> 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).

Documentation effort towards Linux would help get that number up from nobody plus epsilon.

Also, at this point that's just not true because of Android. Most of the userspace is different from normal GNU/Linux distros, but not all: for instance, if your question is "how the heck am I supposed to connect to this WPA-Enterprise network," it's wpa_supplicant under the hood whether you're using Android's network dialog or GNOME's, and documenting wpa_supplicant's abilities and bugs helps Android users just as much as GNOME users.

Android is only about Java.

The NDK APIs are quite constrained and only meant to be used for Java native methods, real time audio and high performance graphics.

Google can replace the kernel for anything else POSIX like, with the same set of NDK APIs.

Since Android 7, they have been locking down access to anything else not part of the official NDK APIs.

That depends if you're talking about user docs or developer docs. I'm saying that we should document wpa_supplicant as user documentation: if there are caveats like, oh, "Android 5.1 and lower can't connect to TLSv1.2-only PEAP or EAP-TLS networks," that should be documented for end users but is irrelevant for devs since wpa_supplicant isn't accessible to the application at all. It's not a library/API, it's a system daemon.

(But maybe I missed the point and we're specifically talking about developer documentation here?)

I am speaking about developer documentation.

As for user documentation, any OEM is free to do whatever they feel like, so you don't have any guarantee how much of it is actually like AOSP.

Samsung is well known among Android devs for breaking AOSP compatibility.

OS X devs are also devs.

I dunno, they might be strapped for resources. Maybe they could hire a documentation team with all that Apple Music revenue.

Seriously, a company with the more GDP than entire nations should be able to do a better job at documenting than the Fedora team. Even if it is a loss leader.

> In contrast to undocumented free (open) systems?

There's choice so you don't have to use those - https://www.freebsd.org/doc/handbook/

There is no undocumented open source software, the documentation is just in a technical language. This is why learning to program is important, as it also means learning how to read the documentation.

I'm not being factious. We always say that documentation doesn't keep up and that the only real documentation is the code. Ultimately the only reliably documented software is free software.

Code is the end result of a thinking / problem solving process, not the process itself. If I implement a mathematical formula in code, the “documentation” is the academic paper where the formula is described and proved, and the whole context of textbooks and other papers where the relevant terms are defined and abstractions are constructed, not the handful of lines of abstract arithmetic on one-letter variable names in the code. If I throw away the paper, the code doesn’t suddenly become self-documenting.

If you’re going to make such a reductionist definition of “documentation”, why not go all the way: every executable program is just a sequence of clear and simple instructions to the machine. The documentation of what each instruction does is right there in black and white. Why would you need anything else? All programs are documented.

That is indeed the argument and I don't think it is necessarily a bad one.

Academic papers are both jargony and written in specialist notation and are not generally accessible to lay people without background in the field. I don't see how it is really much different.

As a firm believer in the old adage that programs are written for people to read, and only incidentally for the machine to execute, I don't buy into this reductionist argument. Code doesn't become self-documenting automatically, writing self-documenting code is one of those things you learn that makes you a good developer. If you throw away your documentation and then can't read the code, you've written bad code.

Good code can be understood just by reading it. That is practically impossible with binaries.

I think that's kind of jacobolus' point though.

(at the risk of speaking for someone else)...

jacobolus is saying that in both binary and source format, code is readable. It's just a matter of scale as to how readable each is.

Source is an abstraction of the code that is actually running, and documentation should be an abstraction of the source and how the running code works.

You're totally being factious in favor of free software. Not facetious, though, I agree.

To your actual point, what hampers free software more than anything imo is a lack of focus on usability. People buy Apple because, less now than a few yeara ago but still the vast majority of the time, it Just Works. People buy Creative Cloud for much the same reason, and Office 365, and whatever other proprietary products you care to name, because they mostly work reliably, and it's not hard to find help when they don't.

This is the standard free software needs to meet in order to compete. The reason it doesn't, I think, is because the economic incentive to do so is not there. That's not a problem I know how to solve, and I wish I did, because then I'd be able to advocate free software (and hardware!) for general use, as I would strongly prefer to do. As the matter stands now, though, I can't do so without critically damaging my credibility with those among whom I would so advocate.

That's a problem that needs to be solved. How does it become so?

> "I can't do so without critically damaging my credibility with those among whom I would so advocate."

I know. I've have had friends who I installed linux on their computer then call me in a few months describing some strange problem, probably related to a broken update, and then in a few months I cringe when I see them buying the latest Apple product but understand why. I worry they think less of free software after that experience.

They do, and justifiably so.

ElementaryOS seems to be going in the right direction. But I suppose the main "thing that works" is to have a team of people that actually enjoy making software usable by the masses rather than solving X for their own needs.

That's a rare sort of intrinsic motivation, though, and tends not to last long in the face of frequent contact with users who, having their own situations to deal with, reasonably tend more often to complain about software that fails to make their lives easier than compliment that which does. That's where extrinsic motivation needs to come into play, but it's not much on offer in the context we're considering.

maybe can get doc writers who care more about people rather than things...

Well, in that way, there's no undocumented proprietary software either. The documentation is just in an even more technical language, called machine code.

The documentation is available in books people are supposed to buy.

I don't disagree with you, but I feel this misses the point about technical documentation. Code tells you how something works, but it doesn't tell you why it works that way - which is often just as important.

Unless we start writing paragraphs of comments for every little five line function, there will still be a need for technical documentation outside of code.

Well then maybe we all should write enough comments and tests to fully document behavior.

Straight from the article:

> Most open source projects are proud to have user documentation which is an order of magnitude better than anything provided by Apple for macOS.

> In contrast to undocumented free (open) systems? Documentation is an issue irrespective of prorietariness(??!) of a system.

Windows and Android had much better documentation than Linux for a long time.

That is one of the major reason of why they are where they are nowadays.

It's much easier to document things when you can dive into the source-code.

At least with the free software, you can hope to accurately document it.

Best: We need to stop making our preference on software an ethical issue and accept that proprietary software isn't bad just because it's not free.

I'd posit that ethical reasons are a great basis to choose software. You either support the values that your software espouses or you don't. There isn't a correct answer there.

Stallman has a "Why Open Source Misses the Point" article that I find pretty compelling. It suggests you should support Free Software because it's the right ethical thing to do, not because of the many instrumental utility arguments of the Open Source movement.

He calls out specifically the notion that Open Source is intrinsically higher quality than commercial software. Indeed there are many high quality, well-functioning commercial bits of software out there.

So, either the ethos of Free Software appeals to you, and you should choose it regardless of whether it is the highest quality, or you don't, in which case the function of the software should be your guide. I personally find the ethical argument compelling, and so often do forego "better" software in favor or freer software.

I'd posit that ethical reasons may be the best reasons to do anything at all.

Of course, the debate on how unethical using non-free software is has been going on for decades and both sides have reasonable arguments. Also, we're all people and hypocrites by definition. I do stuff that's against my fundamental morals every day (eg go to the cinema instead of save a life with the same money). Similarly I think I agree with the Stallmans of this world but I use Windows anyway.

But still, "let's not let ethics get in the way of making choices" isn't the best argument I've ever read on HN :-)

Or maybe abandon strictly ideological and polarizing standpoints, accepting that most people are productive in different ways than our own, and conceding that not giving a damn about distros, dependencies and command line interaction doesn't make you a evil operator of the IT Satan?

And use what? Windows spies on you and they call it a feature. Linux is a great server OS but a really terrible choice on the desktop. I'm not convinced that free software documentation is any better, either.

macOS is the best desktop OS going, for the moment.

> "but a really terrible choice on the desktop"

This is a very subjective claim. Maybe a long long time ago you could say this, but not the case today.

> "not convinced that free software documentation is any better"

That's beside the point. If that were true, that is an argument for focusing a community effort at improving documentation for a free desktop. And actually with linux the problem is not as much a lack of documentation, but rather that the documentation is a little overwhelming, because it is just too specific or technical. (ever typed "man" something in a terminal?)

I shouldn't have to go to terminal to edit a conf file to make audio or video work. I have every single time I have tried Linux on the desktop. It does not work out of the box. You must know how to use terminal and edit Byzantine configurations, and read Linux forum posts from 2005 to make basic functionality work. It's my "subjective" opinion, but after 5+ hours troubleshooting and configuring as a power user who does know how to edit conf files I wouldn't recommend it to anyone.

> I shouldn't have to go to terminal to edit a conf file to make audio or video work.

I never needed to.

> It does not work out of the box.

It does.

> You must know how to use terminal and edit Byzantine configurations, and read Linux forum posts from 2005 to make basic functionality work.

What was your problem?

> It's my "subjective" opinion, but after 5+ hours troubleshooting and configuring as a power user who does know how to edit conf files I wouldn't recommend it to anyone.

You're lying, if you'd be a "power-user" then you wouldn't complain about manual text-based configuration.

Seriously - I prefer text-based config via CLI

That's it though, it very often does just work.

Without vendor support and with barely any investment from manufacturers, the Linux community is still pushing on to get things to a point where your dog could install it.

Your experience is an anomaly they're trying hard to eradicate.

I understand that, and have tried again nearly every year for the past 15, using the most "user friendly" distro I can find each time.

I don't mean to say that there aren't problems, just that they are fewer today than ever before.

It only takes a particularly new graphics card, or certain wireless chipset to give even battle-hardened users a novel and painful experience.

Apple devices are fine-tuned to run macOS. It doesn't make sense to compare a MacBook to some random Linux installation on incompatible hardware.

Buy one of those Developer Edition Dell laptops to even the field, and compare then.

They are almost impossible to buy in Germany.

Audio has "just worked" for years now, thanks to PulseAudio. Video was a mess for a while, but now it will generally work great out of the box if you've got Intel or AMD graphics. Nvidia is still a mess, but Nouveau will work fine for non-gaming stuff.

> "Audio has "just worked" for years now, thanks to PulseAudio."

For your use cases perhaps, but it's not suitable for all use cases in the same way CoreAudio on OSX is. Music production is a key weak point, which is why JACK and PulseAudio are both required to have what CoreAudio offers out of the box.

There are a few options to allow for Jack and PulseAudio to coexist: http://jackaudio.org/faq/pulseaudio_and_jack.html

There is a reason why there is both Jack and Pulse...they meet different needs (pro-audio vs desktop), and it is not necessarily a bad thing to have separate tools to handle separate needs.

> "and it is not necessarily a bad thing to have separate tools to handle separate needs."

It's not a bad thing to have different high-level tools for different needs, but in the case of lower level frameworks it's suboptimal unless interoperability is seamless. In the case of PulseAudio and JACK that interoperability is not seamless, and is fraught with problems, so in this regard Linux audio is worse than CoreAudio.

I'm going to strongly disagree with you. Audio still has a lot of problems experienced by a lot of people. These naive statements are why people get frustrated with Linux. I strongly support FOSS software and use it all day, everyday, but we need to stop saying that our shit doesn't stink.

I've got Nvidia - probably the core of my problems then.

Yes, it is.

For example, there was an article recently, how Nvidia isn't going to support OpenGL acceleration in XWayland.

The keyholder to solve the problems with NV cards in Linux is Nvidia itself. They have all the info, all the sources, and whatever roadmap they planned.

Linux community can solve only Intel and AMD problems, and that's because Intel and AMD are cooperating. Nvidia isn't (Linus' middle finger says hello).

Meanwhile, it is up to you as an consumer, to vote with your wallet and use that to show the vendors your preferences.

Not sure why NIVIDIA should even invest any time in XWayland. It is just a stepping stone towards Wayland, and the retirement of X11

The reason are: games.

All the games (which are of course binary-only, often 32-bit only) released for Linux are linked against SDL 1.2/SDL 2 and X11. It means, that if you are Nvidia owner, you cannot switch to Wayland, unless you are willing to give up gaming (in the current session, at least).

On the other hand, who is buying Nvidia cards? Gamers.

So by not having OpenGL support in XWayland, they have to choose what kind of session they want to run. Many are of course going to choose X11, thus slowing down the adoption of Wayland, delaying the retirement of X11 and of course losing some benefits of Flatpaks (namely isolation at GUI server).

> For example, there was an article recently, how Nvidia isn't going to support OpenGL acceleration in XWayland

Note: Xwayland, not Wayland itself.

Xwayland is the X11-emulation server running inside Wayland (which itself is HW accelerated).

Not saying anything you claim is wrong, but it's easy to interpret wrong so posting for clarity.

> Linux is a great server OS but a really terrible choice on the desktop.


Because I spent 4 hours today trying to figure out how to prevent something from starting on boot (which boot system is Ubuntu using this version? Why do the systemctl and service commands disagree with each other?). I spent two weeks trying to make my ctrl/capslock swap stick and not reset every time the computer slept/resumed. When I plug my headphones into the computer, I have to manually switch the output source every time. If I plug in my external monitor while the monitor is off and then turn it on, linux refuses to recognize it. I have to unplug it, turn the monitor on and plug it back in. Sometimes, when I plug the external monitor in, it won't retain the settings from the last time I used it. It could do the same thing 9 times out of 10, but that 10th time it will decide to mirror the display instead of extend it or something equally silly. Now I have to spend time to fix something that should have just worked.

Is that enough for now? I could go on. I'm using Ubuntu 17.04. Linux on the desktop is still not as easy to use or predictable as Windows or OS X. It's the predictable part that's a deal breaker for me. I want my OS to respond the same way every time I do something, even if that way is wrong or annoying. Every time I sit down to do some work, it's a toss of the dice whether I'll be able to just get into it or if I have to spend some amount of time fixing or resetting or otherwise dealing with nonsense.

A lot of those issues result with non-uniform hardware. If you want predictability with that then buy from a manufacturer who has designed for and preinstalled Linux, like one of those Dells.

It's a Lenovo W530 Thinkpad. It uses standard hardware that Ubuntu officially supports. Been there. Done that. Also keep in mind I've been using Linux off and on since 1999. I'm not a stranger to hardware compatibility issues and none of these problems result from that.

You're using linux from 1999 and you've problems like this: "I spent two weeks trying to make my ctrl/capslock swap stick and not reset every time the computer slept/resumed."? It's unbelievable.

> Because I spent 4 hours today trying to figure out how to prevent something from starting on boot

Learn systemd then? Or use the "Startup" app?

> I spent two weeks trying to make my ctrl/capslock swap stick and not reset every time the computer slept/resumed.

xmodmap or gnome-tweak-tools?

> When I plug my headphones into the computer, I have to manually switch the output source every time.

I never needed to. See your settings.

> If I plug in my external monitor while the monitor is off and then turn it on, linux refuses to recognize it.

That's your window manager.

> Is that enough for now? I could go on.

Going on with what? With pure laziness from your side to look up tutorials? Or that you use one of the worst window manager/desktop on linux in its almost-beta version and complain about it?

> I'm using Ubuntu 17.04.

That's your problem. 16.04 or switch distros. Don't use unity either. Don't expect things to work when you use (practically) unstable stuff and you don't even know what you're doing.

> Linux on the desktop is still not as easy to use or predictable as Windows or OS X.

None of your claims are true. Just because you misconfigure something somewhere or because you use a crappy window manager it doesn't make the "linux desktop" worse. Windows is not predictable either - I'm forced to use it at work and it's a pretty bad experience overall.

Sad to see this simple reply downvoted for no reason by a bunch of Apple fanboys.

Just in case no-one read the leaflets that came with their new Mac, Apple has fairly comprehensive macOS documentation online:


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.

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.

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/Dar...

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.

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.

Not only that but also tooling (Visual Studio) and community development(Codeplex, Codeproject).

The Android ecosystem is not bad, also.

> 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.

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.

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.

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.

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.

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.

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/Pe...

If you haven't already, join the MacAdmins Slack. 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.

> 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

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.

> 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?

Actually you still own the device just not the stuff making it actually useful. That is still owned by apple. (EULA)

>> "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...

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...

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. :(

I remember reading about them in the second paragraph of the article... ;-)

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.

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'.

Open-source documentation (PRs requested!) on macOS security & privacy: 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."

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

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

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 "...".

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.

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.

> 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


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

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

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.

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

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.

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.

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.

> 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.

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.

> 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.

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.)

It's old (circa 2006) and really low level, but I loved reading through Mac OS X Internals (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.

Launchd documentation:


See more documents linked at the bottom of that page.

Nice, XML config. I wonder if Apple employees are internally allowed to voice criticism.

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.

> 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.

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.

It intended for OS X and iOS developers, which use the official supported debugger, lldb.

In other words writing systems software for OS X if you are not employed by Apple is a fools errand?

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.

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.

The onus is on gdb developers to keep up with the OS API changes, not the other way around.

Gives a fairly balanced view of the picture - http://www.infoworld.com/article/2988096/mac-os-x/sorry-unix... .

As I can not edit my comment any longer, examples how Tru64 made use of Security Integration Architecture, are described on the "Security Programming" guide, http://h41361.www4.hpe.com/docs/base_doc/DOCUMENTATION/V51B_...

OS X isn't the first UNIX to have a constrained root.

Safety conscious UNIXes like Tru64 did it first.

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.

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.

How to charge you Magic Trackpad:


Also included in paper documentation in the box.

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

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.

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

    > 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.

No we don't have to.

Stop consuming proprietary code from for-profit corporations.

Registration is open for Startup School 2019. Classes start July 22nd.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact