8 ms·

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

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.

igravious 9y ago
> 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.
- captainmuon 9y ago
  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.)
  - ethbro 9y ago
    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.
    - mavhc 9y ago
      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.
      - valuearb 9y ago
        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.
        mavhc 9y ago
        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
        photojosh 9y ago
        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).
  - SwellJoe 9y ago
robbyt 9y ago
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.
gurkendoktor 9y ago
> 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 9y ago
  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 9y ago
    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 9y ago
      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.
blablabla123 9y ago
>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..
- davemp 9y ago
  > 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.
  - 0xcde4c3db 9y ago
    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.
    - thinkpad20 9y ago
      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.
    - BenjiWiebe 9y ago
      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.
masklinn 9y ago
> 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.
- majewsky 9y ago
  > 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.
  - SwellJoe 9y ago
    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.
notalaser 9y ago
> 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.
- fnord123 9y ago
  And yet Apple does not contribute to homebrew at all. The one project that makes osx usable for developers.
  - wbl 9y ago
    They did contribute to Macports which does the same.
  - deleted 9y ago
    [deleted]
  - krrrh 9y ago
    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.
    - herbst 9y ago
      Assuming this happened and lead to anything it is still far from actually supporting it.
      - Gaelan 9y ago
        IIRC Max now works at Apple and is responsible for Swift's package manager.
        shenaor 9y ago
        I think he left sometime last year https://changelog.com/podcast/232 https://changelog.com/podcast/232 they start talking about his departure from Apple at 55 min and 26s, unless he went back recently
nine_k 9y ago
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.
- microcolonel 9y ago
  > 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.
  - nine_k 9y ago
    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.
AceJohnny2 9y ago
> 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.
fundabulousrIII 9y ago
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.

igravious 9y ago

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

captainmuon 9y ago
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.)
- ethbro 9y ago
  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.
  - mavhc 9y ago
    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.
    - valuearb 9y ago
      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.
      - mavhc 9y ago
        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
        photojosh 9y ago
        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).
- SwellJoe 9y ago

robbyt 9y ago

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.

gurkendoktor 9y ago

> 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 9y ago
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 9y ago
  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 9y ago
    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.

blablabla123 9y ago

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

davemp 9y ago
> 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.
- 0xcde4c3db 9y ago
  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.
  - thinkpad20 9y ago
    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.
  - BenjiWiebe 9y ago
    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.

masklinn 9y ago

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

majewsky 9y ago
> 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.
- SwellJoe 9y ago
  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.

notalaser 9y ago

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

fnord123 9y ago
And yet Apple does not contribute to homebrew at all. The one project that makes osx usable for developers.
- wbl 9y ago
  They did contribute to Macports which does the same.
- deleted 9y ago
  [deleted]
- krrrh 9y ago
  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.
  - herbst 9y ago
    Assuming this happened and lead to anything it is still far from actually supporting it.
    - Gaelan 9y ago
      IIRC Max now works at Apple and is responsible for Swift's package manager.
      - shenaor 9y ago
        I think he left sometime last year https://changelog.com/podcast/232 https://changelog.com/podcast/232 they start talking about his departure from Apple at 55 min and 26s, unless he went back recently

nine_k 9y ago

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.

microcolonel 9y ago
> 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.
- nine_k 9y ago
  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.

AceJohnny2 9y ago

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

fundabulousrIII 9y ago

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.