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

On Apple's Piss-Poor Documentation

caseyliss.com

Post reply on HN
Print view View original

111–120 of 348 posts

Re: On Apple's Piss-Poor Documentation

#111

Post by munificent »

ProAm wrote: post #82
wlesieutre wrote: post #2

I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!” Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me. So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medi…

> So instead you end up on 3rd party tutorials...How do you know if the feature changed significantly in the more recent release? I don’t know, but I can tell you where you won’t find out: the official docs. Get ready for documentation subscriptions. I wish I were joking.

> Get ready for documentation subscriptions.

MSDN Library. Everything old is new again.

Re: On Apple's Piss-Poor Documentation

#113

Post by lostgame »

I've been working on a very simple (but extremely useful) WatchOS project I'd like to keep under wraps for the time being, as I think it could certainly sell.

Apple's WatchOS documentation, however; is sparse at best, barely there at worst. It's been a problem with various Apple documentation for years.

Re: On Apple's Piss-Poor Documentation

#114

Post by musha68k »

creativityEng wrote: post #78
musha68k wrote: post #29

I feel as if Apple has let down the software industry by “going with the times” in general. A “north star” to lots of designers and engineers from interaction design all the way down to the systems level. Excellent documentation was part of it. Long game. Best practices. The whole “crafting” DNA seems to have been lost somewhere along the journey. I think it’s also a function of market driven angst and hence not sayi…

There's a huge disconnect between informed consumers and the average Apple product owner. I read an ancedote from an aspiring SWE that after he saw the Apple product he couldn't afford, he knew he needed it. People aren't buying because quality reasons, they buy because of various psychology tricks their marketing department is responsible for. It creates a system where developers are dragged along to support 100% of…

I actually disagree completely. Your answer does not relate to my comment at all.

This is about “Apple losing the functional high-ground” (which they clearly had at one point) in terms of design, architecture and general “DX”.

All in comparison to its own previous high quality.

In terms of quality of products they still are best in their respective class IMHO. Security, usability and durability are still great/good enough. This has nothing to do with marketing.

Re: On Apple's Piss-Poor Documentation

#115

Post by elpakal »

wlesieutre wrote: post #2

I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!” Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me. So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medi…

They have an `API Changes: Hide/Show` thing on their documentation (on the right, top) that I think is new fwiw.

https://developer.apple.com/documentation/swiftui/progressvi...

Re: On Apple's Piss-Poor Documentation

#116

Post by gentleman11 »

wlesieutre wrote: post #2

I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!” Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me. So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medi…

Unreal engine is like that, except with fewer third party tutorials. It’s getting better but the c++ docs are almost as bad as having nothing. Some of them only have comments like “maybe refactor this” as a description, and the community wiki was taken down recently too

Re: On Apple's Piss-Poor Documentation

#117

Post by terhechte »

wlesieutre wrote: post #24
ChrisMarshallNY wrote: post #21

Earlier quoted context omitted.

SwiftUI's docs are a nightmare. Here's a pretty damn cool app: https://swiftui-lab.com

Excellent, thanks for this! Most recent post is "Attributed Strings with SwiftUI" which is something I was wondering about. There's plaintext TextEditor view, but for rich text editing the impression I've gotten is to either fall back to something in UIKit or do it in a WebView. Will check this post out tonight, it might not change anything but I'd at least like a better idea where things stand in SwiftUI. Props to A…

Yeah, for rich text you need to wrap a UITextView, there's currently no other way to do that. Also, if you have a large amount of text, TextEditor won't cut it either.

Even displaying rich text (non editable) is a wee bit tricky and severely under documented.

Re: On Apple's Piss-Poor Documentation

#118

Post by monknomo »

rocqua wrote: post #32
kaycebasques wrote: post #16

I've been a technical writer for ~8 years (3 at a startup, 5 at Gooble). I don't know Apple's situation but here's my guess: > Is the documentation team too small? (Likely.) Documentation is weird because there seems to be widespread agreement among developers about how lacking it is (and conversely I think it's safe to say how important it is for job success) yet technical writing is almost always understaffed, no m…

> I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links at the bottom of pages, followed by an opportunity to provide freeform feedback. Whilst this is great, I think most people perceive documentation differently. Rarely does documentation delight me in the sense that I'd leave feedback. Generally, my interaction with documentation is one of "It works as ex…

establishing a DSAT metric is still powerful. Lifting a key feedback metric from "this is bullshit" to "this is ok" is something you can sell management on

Re: On Apple's Piss-Poor Documentation

#119

Post by plorkyeran »

wlesieutre wrote: post #6
wlesieutre wrote: post #2

I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!” Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me. So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medi…

I will say that the WWDC sessions are well presented, and are a good place to start. But you can't use a video for quick reference, and you might be missing context from knowing how it worked the previous year to understand what the new enhancements are. Expect to dig into 2019 videos too. SwiftUI being new at least has the benefit that its sessions can't be any more outdated than that (yet). At most you're reconcili…

I don't really consider most WWDC videos documentation. They're usually just marketing videos which show off the new features. Even the more in depth videos are rarely more than a shallow introduction.

Re: On Apple's Piss-Poor Documentation

#120

Post by grimjack00 »

lostcolony wrote: post #86
wlesieutre wrote: post #2

I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!” Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me. So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medi…

I've run into this more often than I can count with Java based things. "Just look at the Javadocs!" You...you mean the auto-generated API descriptors that have exactly zero usage information on them, and expect me to figure out how to piece things together just by type signature? That...that isn't how documentation works.

You mean you can't figure things out from "public Session getSession(String, String, String, String, String)"?
Post reply on HN