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

The Elephant at WWDC

eclecticlight.co

Post reply on HN
Print view View original

61–70 of 213 posts

Re: The Elephant at WWDC

#61

Post by ChrisMarshallNY »

jeffreyrogers wrote: post #17

I've been playing around with Swift/SwiftUI recently and while the documentation is still unclear in some areas, it is significantly better than the documentation for their Objective-C APIs was a few years ago when I was trying to make an iPhone app. Edit: Why is this downvoted? Do people really think the documentation got worse over the past few years?

I am not a fan of the SwiftUI docs, but I have yet to do a full-fat SwiftUI app.

I was introduced to this app, which I think is a great help (I referenced it above): https://swiftui-lab.com/companion/

Re: The Elephant at WWDC

#62

Post by valuearb »

rleigh wrote: post #11
jtdev wrote: post #3

Earlier quoted context omitted.

A good coder does not a good technical document writer make.

I disagree. If a programmer cannot articulate their thoughts and ideas clearly, and cannot effectively communicate with others through writing, I would question whether they fully understand the concepts themselves, and whether they are actually a good programmer. Being able to write is a skill in its own right, but it's one which anyone can acquire with practice, and it's one which many programmers would benefit gre…

Good technical documentation needs dedicated technical writers.

Comments and internal docs can be handled by the engineers themselves, but turning that into an organized and properly formatted manual in a consistent style and voice for outside consumption is a specialized task that can’t be done piecemeal by the same people writing the code.

Re: The Elephant at WWDC

#63

Post by dcow »

alisonkisk wrote: post #54
defaultname wrote: post #44

Earlier quoted context omitted.

Microsoft has had superb documentation for decades. They put a lot of emphasis on it and the results show. The linked article is a bit off base, I think, because clearly Apple's documentation problem isn't a tool issue. It's a philosophy of documentation. I like going to the documentation for a critical system API class and finding all of the members, examples for each, and then "related" things. Philosophically Appl…

Do you really think that's a "philosophy" and not just thoughtless careless underinvestment?

What’s the real difference? It’s the same with good testing. Engineers are expected to operate on timelines and meet deadlines that are often not generated by someone who values good testing and thorough documentation. If Apple wanted good documentation they would have to be comfortable with something that was going to take one week now taking two weeks and they’d probably need to include willingness and ability to document as something they select for when hiring. Or they’d have to spin up documentation teams that work alongside feature engineers, or something. In almost every environment I’m been in, people balk when you force them to confront the reality that good quality things take time and effort. So I don't think it’s just a careless “whoops we forgot to tell the engineers to document” type of scenario. I think it is fundamental to the fabric of the company and those that operate it.

Re: The Elephant at WWDC

#66

Post by microtherion »

leoc wrote: post #7

Wasn’t the original Inside Macintosh supposedly a nightmare? Did it improve dramatically over the lifetime of (classic) MacOS?

The original Inside Macintosh was quite decent. The main problem, I think, was that it was hard to understand just pieces of it; if you read it cover to cover it was pretty good. But by the time Inside Macintosh VI rolled around with its 1750 pages to cover the System 7 additions, that approach had run its course.

Apple then reorganized and rewrote the entire documentation along functional lines, producing separate, smaller, volumes for e.g. Memory, File Management, etc. That New Inside Macintosh series was, in my opinion, the highest quality documentation Apple ever produced.

Re: The Elephant at WWDC

#67

Post by hermanradtke »

One of the people who presented DocC used to lead both the rustdoc and docs.rs teams. You can see Ferris, the Rust mascot, on their desk.

I think quality documentation can be written within the markdown that explains how higher levels concepts work. I see this in Rust all the time.

Re: The Elephant at WWDC

#68

Post by defaultname »

alisonkisk wrote: post #54
defaultname wrote: post #44

Earlier quoted context omitted.

Microsoft has had superb documentation for decades. They put a lot of emphasis on it and the results show. The linked article is a bit off base, I think, because clearly Apple's documentation problem isn't a tool issue. It's a philosophy of documentation. I like going to the documentation for a critical system API class and finding all of the members, examples for each, and then "related" things. Philosophically Appl…

Do you really think that's a "philosophy" and not just thoughtless careless underinvestment?

I mean, generating a list of classes and their members, hierarchies and relationships, with basic annotations, is the easiest, most mechanically automated solution possible. Apple's bizarre documentation seems like it would take significantly more work.

It truly seems philosophical. Someone there thinks this is a superior solution.

Re: The Elephant at WWDC

#69

Post by moralestapia »

Something I really loathe about OS X, and it has been becoming worse with time, is the amount of "processes" or whatever that suddenly take 100% CPU. There's no place to find out what they are.

What are they doing, are they from apple or not? You're hopeless, aside from some comments here and there from random members of the community.

To this day, I have no idea what 'powerd' is, for instance.

Re: The Elephant at WWDC

#70

Post by rubicon33 »

jamil7 wrote: post #34
rubicon33 wrote: post #25

Earlier quoted context omitted.

> Anyway, the higher-level documentation is a very different style of writing. It needs to read like a book Totally agree. When I need to learn a new subject like Core Audio or something I get a book.

A bit off topic but do you have any recommendations for learning Core Audio? Last time I was reading old blog posts and header files to do what I needed.

I used this book and I found it to be excellent.

https://www.amazon.com/gp/product/B007R3U9W2/ref=ppx_yo_dt_b...

It is mainly geared toward MacOS development but there is a section specifically about iOS for things like Audio Session. You will probably still need to keep the Apple docs open for iOS specific stuff here and there but in general the book does a GREAT job of bridging audio theory, with apple's architectural decisions, with low level implementation details. IMO thats the great strength of books, they tie it all together and this one - for me at least - checked all the boxes.

Post reply on HN