Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

We need to document macOS

eclecticlight.co

Post reply on HN
Print view View original

191–200 of 266 posts

Re: We need to document macOS

#191

Post by diego_moita »

cptskippy wrote: post #114

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.

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

The Android ecosystem is not bad, also.

Re: We need to document macOS

#192

Post by microcolonel »

digi_owl wrote: post #141
blablabla123 wrote: post #82

Earlier quoted context omitted.

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

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 codeba…

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.

Re: We need to document macOS

#193

Post by pjmlp »

ewjordan wrote: post #25
ben0x539 wrote: post #14

Earlier quoted context omitted.

I mean, I'm not the target audience and I don't have the attachment to OSX as a platform, but if I was gonna expend the energy to document a thing, I'd hope it goes towards a good cause and isn't just free labor for like the richest corp I can think of from the top of my head.

Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux, which nobody plus epsilon uses (except amongst devs). Impact is a big factor in how useful an activity is, even if it's tied to a big company.

OS X devs are also devs.

Re: We need to document macOS

#194

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

Re: We need to document macOS

#195

Post by vidarh »

SwellJoe wrote: post #110
captainmuon wrote: post #86

Earlier quoted context omitted.

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 separa…

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 ecosys…

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/

Re: We need to document macOS

#196

Post by [deleted] »

em3rgent0rdr wrote: post #173
jacobolus wrote: post #34

Earlier quoted context omitted.

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…

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

[deleted]

Re: We need to document macOS

#197

Post by pjmlp »

geofft wrote: post #67
ewjordan wrote: post #25

Earlier quoted context omitted.

Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux, which nobody plus epsilon uses (except amongst devs). Impact is a big factor in how useful an activity is, even if it's tied to a big company.

> Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux, which nobody plus epsilon uses (except amongst devs). Documentation effort towards Linux would help get that number up from nobody plus epsilon. Also, at this point that's just not true because of Android. Most of the userspace is different from normal GNU/Linux distros, but not all : for instance, if your q…

Android is only about Java.

The NDK APIs are quite constrained and only meant to be used for Java native methods, real time audio and high performance graphics.

Google can replace the kernel for anything else POSIX like, with the same set of NDK APIs.

Since Android 7, they have been locking down access to anything else not part of the official NDK APIs.

Re: We need to document macOS

#198

Post by pjmlp »

starsinspace wrote: post #52
eikenberry wrote: post #16

Earlier quoted context omitted.

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.

Well, in that way, there's no undocumented proprietary software either. The documentation is just in an even more technical language, called machine code.

The documentation is available in books people are supposed to buy.

Re: We need to document macOS

#199

Post by pjmlp »

Ezhik wrote: post #116
taurath wrote: post #39

Earlier quoted context omitted.

I shouldn't have to go to terminal to edit a conf file to make audio or video work. I have every single time I have tried Linux on the desktop. It does not work out of the box. You must know how to use terminal and edit Byzantine configurations, and read Linux forum posts from 2005 to make basic functionality work. It's my "subjective" opinion, but after 5+ hours troubleshooting and configuring as a power user who do…

Apple devices are fine-tuned to run macOS. It doesn't make sense to compare a MacBook to some random Linux installation on incompatible hardware. Buy one of those Developer Edition Dell laptops to even the field, and compare then.

They are almost impossible to buy in Germany.

Re: We need to document macOS

#200

Post by lj3 »

em3rgent0rdr wrote: post #188
lj3 wrote: post #150

Earlier quoted context omitted.

Because I spent 4 hours today trying to figure out how to prevent something from starting on boot (which boot system is Ubuntu using this version? Why do the systemctl and service commands disagree with each other?). I spent two weeks trying to make my ctrl/capslock swap stick and not reset every time the computer slept/resumed. When I plug my headphones into the computer, I have to manually switch the output source…

A lot of those issues result with non-uniform hardware. If you want predictability with that then buy from a manufacturer who has designed for and preinstalled Linux, like one of those Dells.

It's a Lenovo W530 Thinkpad. It uses standard hardware that Ubuntu officially supports. Been there. Done that. Also keep in mind I've been using Linux off and on since 1999. I'm not a stranger to hardware compatibility issues and none of these problems result from that.
Post reply on HN