Live data from Hacker News

We need to document macOS

eclecticlight.co

201–210 of 266 posts

Re: We need to document macOS

#201
The most profitable software company ever still can't build software properly (meaning: fully documented). Does this mean that it is impossible to build software properly at scale? Or is it just that you don't become that profitable without cutting a few corners?

(In my original comment I said "most profitable company", but it seems the dutch east india company gave them a run for their money. So, good news for apple, they still have room to grow.)

Re: We need to document macOS

#202
post #181

I just wish apple would stop breaking gdb every release. They need to make up their mind on whether OS X is a general purpose OS intended for developer use or if its just a locked down version of iOS which runs on larger devices.

It intended for OS X and iOS developers, which use the official supported debugger, lldb.

Re: We need to document macOS

#203
post #151

Earlier quoted context omitted.

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

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

Re: We need to document macOS

#204

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…

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.

Re: We need to document macOS

#205

When it's documented it cannot be changed as easily, so it's often better to not document everything in detail.

I agree that there's a trade off between detailed documentation and flexibility, but I think regularly leaving out details to allow for frequent changes can be a red flag. Unless your project is new and in beta, you probably shouldn't be changing things that often. After all, even if your documentation is sparse, users are going to start expecting certain behavior just from using your project.

You can also tweak this tradeoff a little. If you explain up front that what you're describing changes a lot and don't put it in the official documentation [0], you can be somewhat detailed and still have room to change.

[0]: Think a wiki or blog that your project maintains.

Re: We need to document macOS

#206
post #148

Earlier quoted context omitted.

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…

I think the difference is that those weren't created solely for Apple's benefit.

Re: We need to document macOS

#207

Earlier quoted context omitted.

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…

Not sure why NIVIDIA should even invest any time in XWayland. It is just a stepping stone towards Wayland, and the retirement of X11

The reason are: games.

All the games (which are of course binary-only, often 32-bit only) released for Linux are linked against SDL 1.2/SDL 2 and X11. It means, that if you are Nvidia owner, you cannot switch to Wayland, unless you are willing to give up gaming (in the current session, at least).

On the other hand, who is buying Nvidia cards? Gamers.

So by not having OpenGL support in XWayland, they have to choose what kind of session they want to run. Many are of course going to choose X11, thus slowing down the adoption of Wayland, delaying the retirement of X11 and of course losing some benefits of Flatpaks (namely isolation at GUI server).

Re: We need to document macOS

#208
post #180
post #158

Earlier quoted context omitted.

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.

Re: We need to document macOS

#209

If you haven't already, join the MacAdmins Slack. https://macadmins.herokuapp.com It's an open-invite slack team with over 12000 users - sysadmins, MDM developers, security researchers and so on. We have various ongoing efforts to document and improve the macOS experience for users. If you have a macOS question, you'll likely find the answer there.

> you'll likely find the answer there

Well, I hope the Google Bot (plus whichever one DDG uses) also has an invite to that proprietary, closed, messaging system, or that the "macadmins" owner has set up a channel mirroring system ala IRC web logs, otherwise the system you described isn't contributing to the open body of knowledge.

Related, although mildly off topic, :fu: slack search

Re: We need to document macOS

#210

Earlier quoted context omitted.

In contrast to undocumented free (open) systems? Documentation is an issue irrespective of prorietariness(??!) of a system. I welcome this initiative. (Yes I know there are examples of documentation excellence to be found in some free/open systems. You can advocate their use whilst also having well documented macOs.)

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.

Maybe, sometimes, some of us just want to make a thing we use better rather than attaching grandiose moral judgements to the political status of a piece of fucking code.
Post reply on HN