
We need to document macOS - fern12
https://eclecticlight.co/2017/08/13/last-week-on-my-mac-we-need-to-document-macos/
======
SwellJoe
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.

~~~
gurkendoktor
> 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:

[https://blackpixel.com/writing/2012/02/radar-or-
gtfo.html](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.

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

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

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

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

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

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

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

~~~
pebers
I guess the problem is that Apple don't _need_ to do it; lots of people would
like them to do it, and maybe they should do it, but it's not hurting their
bottom line much so they can just continue as they are. Unless a whole heap of
customers suddenly decide to buy different laptops instead over it, but I'd
not be betting on that.

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

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

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

~~~
givinguflac
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...](https://howchoo.com/g/mzuxyjqyzmy/how-to-set-the-view-options-for-
all-finder-windows-in-os-x)

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

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

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

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

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

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

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

[https://support.apple.com/macos](https://support.apple.com/macos)

A lot of this is built into your Mac also, at Help > Mac Help in the Finder.

For those who prefer physical books, I've always found the "Missing Manual"
series to be excellent.

~~~
pfranz
How come I never see them come up in Google searches? I have seen it come up
when looking for conditioning your battery or the shortcut keys for Target
Disk Mode. But more often I'll search for a runaway process name or an OS
message that is spamming Console. The top results are Apple Discussion posts
that go on for pages, but often don't have a clear result. I also recently was
trying to learn more about macOS' init system and got lost like the article
mentioned.

~~~
extra88
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...](https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man8/mdworker.8.html)

------
cptskippy
For all the things that Microsoft takes flak about, this is one of the few
areas you really can't complain much about. They maintain detailed versions
documentation and make it easy to explore.

Every so often I come across something that isn't documented well or at all
and it hurts. But it has a page at least and on every page they have a public
feedback mechanism.

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

The Android ecosystem is not bad, also.

------
unkown-unknowns
> Yet Apple’s documentation for users and those supporting users has all but
> dried up

You and me we both RTFM, but the population at large? Not so much. When
computers were in their early days more of the people that used them were
willing and even interested to learn a lot about what was going on. Now the
computer is a tool used by most people to do specific tasks. Just like I don't
care to learn how to fix my car they don't want to learn how to troubleshoot
software nor hardware problems with their computers.

So it might not make economical sense for Apple to spend any significant
amount of money on employing technical writers.

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

------
userbinator
Apple has always been vague and stingy with the documentation; despite the
author mentioning this,

 _In the days of classic Mac OS, when print publishing was growing as a result
of Macs, Apple published an exemplary series of books under the banner Inside
Macintosh_

I have read the Inside Macintosh books but they still felt somewhat incomplete
and superficial (although they're definitely a little prettier) compared to
what I'd consider close to a "gold standard" for documentation, the _IBM PC
/AT Technical Reference_ and the same one for MS/PC-DOS.

I suppose it had a lot to do with the general attitude of Apple's culture,
summarised in the famous phrase "it just works". The notion that systems
should be designed to be so easy to use and obvious as to require no
documentation, has resulted in a lack of documentation even for those cases
which are _not_ easy to use nor obvious.

~~~
pvg
_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.

------
extra88
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...](https://developer.apple.com/library/content/documentation/Performance/Conceptual/power_efficiency_guidelines_osx/DiscretionaryTasks.html)

------
zalmoxes
If you haven't already, join the MacAdmins Slack.
[https://macadmins.herokuapp.com](https://macadmins.herokuapp.com) It's an
open-invite slack team with over 12000 users - sysadmins, MDM developers,
security researchers and so on.

We have various ongoing efforts to document and improve the macOS experience
for users. If you have a macOS question, you'll likely find the answer there.

~~~
mdaniel
> _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_

------
enqk
This problem is actually the reason I've fallen out of love with Macos as a
platform for my home computers.

There's way too much stuff that goes around, daemons that are waking up at any
given point and doing a lot of I/O, for which there's absolutely no
documentation whatsoever.

It kills the performance on my old Macs and also doesn't inspire confidence
that I'm a user/owner of the device.

~~~
nebabyte
> and also doesn't inspire confidence that I'm a user/owner of the device

...What gave you that delusion? Are you one of those people who clicks "okay"
to EULAs without reading them?

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

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

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

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

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

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

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

------
walterbell
Open-source documentation (PRs requested!) on macOS security & privacy:
[http://www.oss.io/p/drduh/OS-X-Security-and-Privacy-
Guide](http://www.oss.io/p/drduh/OS-X-Security-and-Privacy-Guide)

 _"... a collection of thoughts on securing a modern Apple Mac computer using
macOS (formerly OS X) 10.12 "Sierra", as well as steps to improving online
privacy. This guide is targeted to “power users” who wish to adopt enterprise-
standard security, but is also suitable for novice users with an interest in
improving their privacy and security on a Mac."_

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

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

------
CrazyRabbit
[https://opensource.apple.com/](https://opensource.apple.com/)

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

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

~~~
bastijn
My thoughts exactly. First thought was what problems did this person run into
that can't be found in a single google hit today? I was thinking the piece
would go into some obscure internals but that doesn't seem to be the case.

MacOS is simple enough to grasp for most people at first use. More advanced
usage is documented, not in one location but scattered over the internet.
Google made that not matter anymore.

In addition, most documentation you would need today is for the products you
install I guess, not macOS. But again, it really doesn't matter much with
Google finding anything you search.

My experience with (large) documentation projects. They are outdated almost
always. Q&A style works much better nowadays.

~~~
mdaniel
> _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

------
jalcazar
"We"??

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

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

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

~~~
nebabyte
Apple gives users APIs at the level they think users should be operating, not
system internals.

Are we seriously having this discussion, HN? Did people just wake up today to
what their reality has been for years?
[https://www.youtube.com/watch?v=ilcRS5eUpwk](https://www.youtube.com/watch?v=ilcRS5eUpwk)

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

------
yannovitch
There is a saying in French which says that half of the treatment to get
better is to recognize/admit you're sick . There is an other saying which says
"Faute avouée est à moitié pardonnée" (If you admit a flaw/mistake, you're
already half the way through forgiveness).

That to say that maybe there is a lack of documentation because Apple would
have to admit to itself (...and to the world) that macOS is not the absolutely
perfect OS without any flaws, virus/malware, or room for improvement, that
they want all of us to believe.

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

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

------
e28eta
It's old (circa 2006) and really low level, but I loved reading through Mac OS
X Internals ([http://www.osxbook.com](http://www.osxbook.com))

If it were updated, or a vol2 was released with all the new stuff, I would
immediately buy it.

It's not going to teach you how to use Finder, but you'll have a great
understanding of the internals.

------
st3fan
Launchd documentation:

[https://developer.apple.com/library/content/documentation/Ma...](https://developer.apple.com/library/content/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html)

See more documents linked at the bottom of that page.

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

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

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

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

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

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

~~~
pjmlp
No, a fools errand is to buy a Mac and use GNU/Linux tooling instead of the
official OS X SDK tooling.

GDB stop being part of the official modern SDKs quite long time ago.

~~~
dman
I understand that gdb is not part of the official SDK. I would expect an OS in
widespread use to not break userspace and when it does, take substantial
remedial action to fix / patch widely used applications.

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

~~~
dman
Gives a fairly balanced view of the picture -
[http://www.infoworld.com/article/2988096/mac-os-x/sorry-
unix...](http://www.infoworld.com/article/2988096/mac-os-x/sorry-unix-fans-os-
x-el-capitan-kills-root.html) .

~~~
pjmlp
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_...](http://h41361.www4.hpe.com/docs/base_doc/DOCUMENTATION/V51B_ACRO_DUX/ARSFDATE.PDF)

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

------
st3fan
How to charge you Magic Trackpad:

[https://support.apple.com/en-us/HT205160](https://support.apple.com/en-
us/HT205160)

Also included in paper documentation in the box.

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

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

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

------
charlesism

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

------
qualitytime
No we don't have to.

Stop consuming proprietary code from for-profit corporations.

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

------
st3fan
End user docs about The Dock:

[https://support.apple.com/en-ca/HT201730](https://support.apple.com/en-
ca/HT201730)

More links at the bottom

------
doubleshame
Here are some docs

[http://images.apple.com/server/docs/Command_Line.pdf](http://images.apple.com/server/docs/Command_Line.pdf)

[https://www.apple.com/jp/server/pdfs/Mac_OS_X_Server_v10.2.p...](https://www.apple.com/jp/server/pdfs/Mac_OS_X_Server_v10.2.pdf)

------
gogopuppygogo
This is Apple we are talking about.

If you built a knowledge-base like this on your own time and for the right
reasons I bet they send a DMCA.

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

------
quink
Why bother? If the people making the thing can't be bothered documenting it
you're going to fight an uphill battle. In the long run, for better or for
worse, code is documentation. If the code isn't available there'll be only so
far you can go. And with the unification of iOS and macOS fast approaching the
number of people able to have transparency into even just the POSIX layer is
going to drop another order of magnitude.

macOS is dead, Apple just hasn't told anyone about it yet. And iOS 11 is going
to be it's murderer.

If you have the time to document, you might as well spend the time documenting
Windows, BSD or Linux; Blink or Servo. Or the JS ecosystem.

The Apple specific SMB implementation or APFS or Cocoa are not worth
documenting any more than OOXML would be - only as a specification that one
party has the power to change and to implement. There is no way for the
documentation to be considered prescriptive rather than descriptive for anyone
touching the code. It might be useful in some limited aspect for a limited
time, but it will decay as Apple considers every single pixel their OS is
going to render to be under their control in some way. Apart from what they
can sandbox, which amounts to the web platform, which is plenty documented
already.

> launchd – second only in importance to the kernel – controlled and
> orchestrated most of the services supplied in macOS

Who cares about the launch facilities in macOS when anyone who should care
about launch facilities is going to be using Windows Server, Linux or BSD?
Apple couldn't have been saying fuck off to anyone wanting to screw around
with CUPS or Samba or launchd more loudly unless they shouted it from all the
rooftops in Cupertino.

> Magic Trackpad 2, never knew how to launch an app from the Dock, or couldn’t
> manage their Photos library.

1\. It'll stop working (here we go, top result for a Google search:
[https://support.apple.com/en-us/HT204621](https://support.apple.com/en-
us/HT204621)) 2. Launchpad exists and has a keyboard shortcut and 3. Photos
manage themselves. What does manage even mean in the context of you take a
picture with a phone, it adds geotagging and a time and that's it. What more
do 99% of users want?

