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
3) don't buy their products.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'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.)
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.
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).
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.
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.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.
>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
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.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...
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.
Management probably doesn't even realize this is an issue. Perhaps getting this started will get some visibility on the problem.
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.