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

31–40 of 266 posts

Re: We need to document macOS

#31

Post by lucaspiller »

eikenberry wrote: post #16
mvdwoord wrote: post #11

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

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.

I don't disagree with you, but I feel this misses the point about technical documentation. Code tells you how something works, but it doesn't tell you why it works that way - which is often just as important.

Unless we start writing paragraphs of comments for every little five line function, there will still be a need for technical documentation outside of code.

Re: We need to document macOS

#32

Post by static_noise »

pjc50 wrote: post #10
static_noise wrote: post #7

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

Then your users find that their own memory of where to find things and how to perform tasks is unreliable. Has the system changed or they forgotten it? You're effectively "gaslighting" your users if you rely on this.

If they rely on you (you being apple here). It's their fault for relying on undocumented interfaces. Consequently, they should stop using your system but they don't.

Re: We need to document macOS

#34

Post by jacobolus »

eikenberry wrote: post #16
mvdwoord wrote: post #11

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

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.

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 in the code. If I throw away the paper, the code doesn’t suddenly become self-documenting.

If you’re going to make such a reductionist definition of “documentation”, why not go all the way: every executable program is just a sequence of clear and simple instructions to the machine. The documentation of what each instruction does is right there in black and white. Why would you need anything else? All programs are documented.

Re: We need to document macOS

#35

Post by stuntkite »

OT a bit but I think still related. 8 years ago when I switch to OSX I was furious with finder. Tiny window, no hierarchical browsing and the search just doesn't do shit that is useful.

I normally default to locate or find now so much that I was using it the other day I was reminded about how much it sucked. It's literally identical (aside from tags and labels) to what it was forever ago and is a terrible paradigm. I looked around for a bit for some help on refining the search sensibly and nothing in the OS helped (back on topic!). I've been using a great replacement for Finder called PathFinder that does everything Finder should do, but you can't swap it out. All the native places I access Finder are important inroads. They used to have instructions to hack it but apple shut them down.

I feel more and more like UI and usability innovation totally ate itself and died at maybe a specific moment in time ~6 years ago. Where did the people and companies go that do cool new things? Are the giants on their laurels long enough yet to get eaten? I'd switch totally to Ubuntu or Mint for my desktop work, but I do things that require the adobe suite, I need a trackpad that works as well as the mac one without fighting it, and I want to just solve problems, not fiddle with barely supported gizmos for weeks.

Did we reach the absolute end of all we can do with this juggling of rectangles that display and accept text and now we just get everything that matters to a power user stripped off for the sake of what "most users care about"? I really don't think we have.

I'm still pissed and I still have no answers. My kingdom for a $3000 laptop that "Just works" and helps me murder code, deployment, graphic arts, music, and still loads HBONow.

Re: We need to document macOS

#36

Post by hollander »

unkown-unknowns wrote: post #2

> Yet Apple’s documentation for users and those supporting users has all but dried up You and me we both RTFM, but the population at large? Not so much. When computers were in their early days more of the people that used them were willing and even interested to learn a lot about what was going on. Now the computer is a tool used by most people to do specific tasks. Just like I don't care to learn how to fix my car t…

Not only that, but when I have a problem with my Mac, I go to Stackexchange and ask my question there. Many times I get a useful answer. Apple could set up a team to help people over there, and officially support it, like Ubuntu does. Documenting is one thing, helping people with their questions is the easy way out.

Re: We need to document macOS

#37

Post by throwanem »

eikenberry wrote: post #16
mvdwoord wrote: post #11

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

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.

You're totally being factious in favor of free software. Not facetious, though, I agree.

To your actual point, what hampers free software more than anything imo is a lack of focus on usability. People buy Apple because, less now than a few yeara ago but still the vast majority of the time, it Just Works. People buy Creative Cloud for much the same reason, and Office 365, and whatever other proprietary products you care to name, because they mostly work reliably, and it's not hard to find help when they don't.

This is the standard free software needs to meet in order to compete. The reason it doesn't, I think, is because the economic incentive to do so is not there. That's not a problem I know how to solve, and I wish I did, because then I'd be able to advocate free software (and hardware!) for general use, as I would strongly prefer to do. As the matter stands now, though, I can't do so without critically damaging my credibility with those among whom I would so advocate.

That's a problem that needs to be solved. How does it become so?

Re: We need to document macOS

#38

Post by em3rgent0rdr »

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.

> "Documentation effort towards OSX would help vastly more people than similar efforts for any flavor of Linux"

From a purely utilitarian perspective:

- The same amount of effort spent trying to document will result in more documentation being produced on a free system, since free systems are easier to document.

- The same amount of documentation produced will result in more benefit from end users for a free system, because more people will be able to use a free system.

Re: We need to document macOS

#39

Post by taurath »

em3rgent0rdr wrote: post #29
LeoPanthera wrote: post #24

Earlier quoted context omitted.

And use what? Windows spies on you and they call it a feature. Linux is a great server OS but a really terrible choice on the desktop. I'm not convinced that free software documentation is any better, either. macOS is the best desktop OS going, for the moment.

> "but a really terrible choice on the desktop" This is a very subjective claim. Maybe a long long time ago you could say this, but not the case today. > "not convinced that free software documentation is any better" That's beside the point. If that were true, that is an argument for focusing a community effort at improving documentation for a free desktop. And actually with linux the problem is not as much a lack of…

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 does know how to edit conf files I wouldn't recommend it to anyone.

Re: We need to document macOS

#40

Post by stuntkite »

mvdwoord wrote: post #11
em3rgent0rdr wrote: post #5

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

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 dunno, they might be strapped for resources. Maybe they could hire a documentation team with all that Apple Music revenue.

Seriously, a company with the more GDP than entire nations should be able to do a better job at documenting than the Fedora team. Even if it is a loss leader.

Post reply on HN