We need to document macOS
eclecticlight.co
eclecticlight.co
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.
> 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.
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 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.
If you have 50% of your OS programmers working on an OS that only 10% of your users use, seems like a waste
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).
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.
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.
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.
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.
Management probably doesn't even realize this is an issue. Perhaps getting this started will get some visibility on the problem.
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:
https://blackpixel.com/writing/2012/02/radar-or-gtfo.html
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.
Especially when the first party could hire technical writers for a fraction of the cost of developers and make this problem disappear.
Or, write a complete reference book and sell it for profit.
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.
1) be influential, 2) complain publicly
>decades...where docs are copious but wrong about 50% of the
>time.
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..
How long ago was this? Checkout the arch linux wiki. It's a pretty great resource for all things GNU/linux.
I used Arch wiki to finally get it figured out, iirc.
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.
Never mind that calling it a init is a mislabeling at best...
# man pdftohtml
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...
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] ...
-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.
Interestingly, systemd (which, AFAIK, is influenced in large parts by launchd) goes the exact opposite way and has amazingly complete and well-structured documentation.
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.
Unfortunately, cron and crontab only function as expected in every other (every third ?) release of OSX.
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.
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.
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.
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.
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.
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.
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.
Very hard to say if the problem is serious enough yet though.
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.
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.
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.
But this is great info and will definitely keep be from cursing quite as much next time I'm MS admining.
It's 2017 and I still can't use the keyboard to copy and paste from and to a Windows command line window...
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.)
Windows has better keyboard accessibility than any other desktop OS.
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.
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.
UI fashions come and go, but the terminal is forever.
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.
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 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.
- 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
defaults write com.apple.Finder AppleShowAllFiles YES
> 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.
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).
- 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.
plutil -convert xml1 com.apple.Finder.plist
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:
https://developer.apple.com/library/content/releasenotes/Dat...
Sorry for the points that were unclear. They are general frustrations that I've had. This looks like it'll help with a lot!
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.)
Impact is a big factor in how useful an activity is, even if it's tied to a big company.
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.
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.
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.
(But maybe I missed the point and we're specifically talking about developer documentation here?)
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.
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.
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.
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.
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.
(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.
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 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.
There's choice so you don't have to use those - https://www.freebsd.org/doc/handbook/
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.
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.
> Most open source projects are proud to have user documentation which is an order of magnitude better than anything provided by Apple for macOS.
macOS is the best desktop OS going, for the moment.
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?)
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.
It only takes a particularly new graphics card, or certain wireless chipset to give even battle-hardened users a novel and painful experience.
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.
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).
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.
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 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.
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 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.
Buy one of those Developer Edition Dell laptops to even the field, and compare then.
Why?
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.
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.
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.
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 :-)
https://support.apple.com/macos
A lot of this is built into your Mac also, at Help > Mac Help in the Finder.
For those who prefer physical books, I've always found the "Missing Manual" series to be excellent.
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...
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.
The Android ecosystem is not bad, also.
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.
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.
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.
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.
[0] https://developer.apple.com/library/content/documentation/Pe...
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.
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
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.
...What gave you that delusion? Are you one of those people who clicks "okay" to EULAs without reading them?
The author of this article fails to realise that the Mac is not Apple's flagship product anymore...
Just sayin'.
"... 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."
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.
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.
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
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.
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.
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.
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.
(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.)
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.
https://developer.apple.com/library/content/documentation/Ma...
See more documents linked at the bottom of that page.
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.
GDB stop being part of the official modern SDKs quite long time ago.
Safety conscious UNIXes like Tru64 did it first.
https://support.apple.com/en-us/HT205160
Also included in paper documentation in the box.
> 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.
Stop consuming proprietary code from for-profit corporations.
https://support.apple.com/en-ca/HT201730
More links at the bottom
If you built a knowledge-base like this on your own time and for the right reasons I bet they send a DMCA.
Why do you say that? Your post makes me think I'm ignorant of Apple's past litigation.
macOS is dead, Apple just hasn't told anyone about it yet. And iOS 11 is going to be it's murderer.
If you have the time to document, you might as well spend the time documenting Windows, BSD or Linux; Blink or Servo. Or the JS ecosystem.
The Apple specific SMB implementation or APFS or Cocoa are not worth documenting any more than OOXML would be - only as a specification that one party has the power to change and to implement. There is no way for the documentation to be considered prescriptive rather than descriptive for anyone touching the code. It might be useful in some limited aspect for a limited time, but it will decay as Apple considers every single pixel their OS is going to render to be under their control in some way. Apart from what they can sandbox, which amounts to the web platform, which is plenty documented already.
> launchd – second only in importance to the kernel – controlled and orchestrated most of the services supplied in macOS
Who cares about the launch facilities in macOS when anyone who should care about launch facilities is going to be using Windows Server, Linux or BSD? Apple couldn't have been saying fuck off to anyone wanting to screw around with CUPS or Samba or launchd more loudly unless they shouted it from all the rooftops in Cupertino.
> Magic Trackpad 2, never knew how to launch an app from the Dock, or couldn’t manage their Photos library.
1. It'll stop working (here we go, top result for a Google search: https://support.apple.com/en-us/HT204621) 2. Launchpad exists and has a keyboard shortcut and 3. Photos manage themselves. What does manage even mean in the context of you take a picture with a phone, it adds geotagging and a time and that's it. What more do 99% of users want?