Live data from Hacker News

We need to document macOS

eclecticlight.co

151–160 of 266 posts

Re: We need to document macOS

#151

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

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.

Re: We need to document macOS

#152

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

Best: We need to stop making our preference on software an ethical issue and accept that proprietary software isn't bad just because it's not free.

I'd posit that ethical reasons may be the best reasons to do anything at all.

Of course, the debate on how unethical using non-free software is has been going on for decades and both sides have reasonable arguments. Also, we're all people and hypocrites by definition. I do stuff that's against my fundamental morals every day (eg go to the cinema instead of save a life with the same money). Similarly I think I agree with the Stallmans of this world but I use Windows anyway.

But still, "let's not let ethics get in the way of making choices" isn't the best argument I've ever read on HN :-)

Re: We need to document macOS

#153
post #105

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…

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.

Re: We need to document macOS

#154
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. :(

Re: We need to document macOS

#155

Earlier quoted context omitted.

> Lets just say specifically the Finder issue. Is the solution to use Linux as my desktop environment? Yes, especially with KDE's Dolphin file manager which is more or less the pinnacle of GUI file browser. See https://www.youtube.com/watch?v=jkWuVCKpiXs it becomes especially good when you start taping in its scripting capabilities and the wealth of scripts available: https://store.kde.org/browse/cat/102/ .

Please be cautious about recommending KDE's Dolphin. According to Hanno Böck in https://media.ccc.de/v/SHA2017-148-improving_security_with_f... , KDE are refusing to sandbox the thumbnail/preview code, which has proven to be riddled with easy-to-find bugs (using software fuzzing)

how do we know there aren't similar bugs with MS explorer / Finder ?

Re: We need to document macOS

#156

Earlier quoted context omitted.

I have not used smart searches, and now I'm reading about them and it does look pretty cool. But that search bar should give me something sort of close to what I'm looking for in a couple strokes and it really doesn't. I can specifically call out what my issues are with Finder. - Where is my fucking folder tree. There was no reason to take it away other than "thinking different" just like the backspace key. Super spe…

A lot of these just seem like you aren't familiar with the Finder, did you check the menus, preferences, or do a web search for Finder tips? - No folder tree you are correct. I don't miss it personally. Gotta just deal with this one I think. - What way specifically does the search not work for you? It's incredibly powerful and you can search by file name, content, file type, creation date, etc. - It should save the w…

I'm not GP, but I recently sank time into trying to change Finder searches to default to the current directory instead of my entire machine. It mildly infuriates me that I can't change this; I gave up after I saw com.apple.finder.plist is not plaintext.

Re: We need to document macOS

#157
It's old (circa 2006) and really low level, but I loved reading through Mac OS X Internals (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.

Re: We need to document macOS

#158

Earlier quoted context omitted.

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

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.

Re: We need to document macOS

#159
post #113

Earlier quoted context omitted.

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

Re: We need to document macOS

#160
post #55

Earlier quoted context omitted.

I've got Nvidia - probably the core of my problems then.

Yes, it is. For example, there was an article recently, how Nvidia isn't going to support OpenGL acceleration in XWayland. The keyholder to solve the problems with NV cards in Linux is Nvidia itself. They have all the info, all the sources, and whatever roadmap they planned. Linux community can solve only Intel and AMD problems, and that's because Intel and AMD are cooperating. Nvidia isn't (Linus' middle finger says…

> For example, there was an article recently, how Nvidia isn't going to support OpenGL acceleration in XWayland

Note: Xwayland, not Wayland itself.

Xwayland is the X11-emulation server running inside Wayland (which itself is HW accelerated).

Not saying anything you claim is wrong, but it's easy to interpret wrong so posting for clarity.

Post reply on HN