Hacker News Reader

> 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

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

Ah.

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

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

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