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

201–210 of 348 posts

Re: On Apple's Piss-Poor Documentation

#201

Post by freeone3000 »

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.

https://docs.oracle.com/javase/8/docs/api/java/time/Clock.ht... is a bit more involved than the autogenerated template. The Oracle documentation tends towards this level -- the javadoc template is simply where the docs are kept.

Re: On Apple's Piss-Poor Documentation

#202

Post by bluGill »

throwaways885 wrote: post #154
dragonwriter wrote: post #143

Earlier quoted context omitted.

> The MSDN documentation has always been freely available No, it hasn't. It was originally available exclusively to subscribers, and only on CD. MSDN started before the web existed. Eventually , the documentation became free on the web.

That's a bit unfair. The web is what made it easy to publish at no cost, CD's still had mail and print costs associated so it made sense to send documentation with the software packages it... documented.

Perhaps, but they didn't charge $3 for the CD, which is about the incremental cost of making a copy and mailing it out would be.

Re: On Apple's Piss-Poor Documentation

#203

Post by actuallyalys »

qppo wrote: post #167
fivre wrote: post #61

Earlier quoted context omitted.

> technical writing is almost always understaffed > it's really hard to show a causal link between the docs we create and developer success Amen to that. IMO good documentation is incredibly valuable, but not in a way that aligns with business priorities. At my current job, we hear, repeatedly, that our documentation is poor, and that we need to improve it. Execs echo this sentiment, but the status quo doesn't budge.…

> the writers are all generalists, covering every product from top to bottom. In practice, this means that engineers are asked to draft the bulk of documentation, and the writers scramble to at least copy-edit it. This seems like an organizational/staffing mistake. In other engineering orgs you'd see these roles filled by applications engineers, who dogfood while evangelizing the product and writing its technical doc…

I do think hiring application engineers with that kind of job description is one solution, but so is having a larger number of technical writers so they don't need to be generalists.

Re: On Apple's Piss-Poor Documentation

#204

Post by ethbr0 »

wlesieutre wrote: post #192
jjkaczor wrote: post #175

Earlier quoted context omitted.

For all the crap that Apple, Java and other open-source people have piled on Microsoft over the years, their developer documentation has always been very good. Yes, there are rough-edges. Back in the day, when Sun was still in-charge of Java, I had my 1-person consulting company partner with Sun and become an official "Certified Java" organization... Great, I thought - now I can get some better documentation... Sure,…

There's an old saying at Microsoft: developers, developers, developers, developers, developers, developers, developers, developers

It's mocked, but the underlying observation is astute.

In the personal computing world, first parties can't build enough user software.

Furthermore, software availability and reliability lag third party developer and development ecosystem health. A bad experience doesn't hurt the platform today, it hurts the platform in 1+ years.

And perhaps even worse, steps to address it take effect over a 1+ year timeframe as well.

Apple's been able to leverage iOS market share into papering over the desktop reality, but they're going to find the emperor has no clothes real quickly if anything about that calculus shifts in a bad way.

Re: On Apple's Piss-Poor Documentation

#205

Post by sixstringtheory »

andromeduck wrote: post #135
njhaveri wrote: post #85

Earlier quoted context omitted.

I also really dislike that WWDC videos are now the de-facto documentation. It must be a lot of work to put them together – I wish they'd just write a doc instead. Would be way faster to read, search, etc. and could probably go into much greater depth.

Example programs would be nice too.

Many of them do come with sample code, but like the content of the sessions themselves, they age out very quickly.

Re: On Apple's Piss-Poor Documentation

#206

Post by mschuster91 »

zentiggr wrote: post #186
gumby wrote: post #169

Earlier quoted context omitted.

This is a common, lazy argument. Apple's bundled apps are typically MVPs rather than best of breed. For me an MVP is perfectly fine for my photos and video editing while, say, for calendar and address book I use third party apps. I doubt anyone would claim that Pages or Numbers are any sort of competition for flagship apps like Word or Excel, while at the same time they don't even break new ground like google docs di…

I'm sensing an assumption that Apple needs their in house apps to be best of breed. I'm not an iOS or macOS user, but I've worked on systems over the years. It really seems like they're happy to let someone get popular to identify the niche that needs to be filled, roll an MVP to cover it, and kick out the originators with no real excuses. It's like they're still focused on hardware development and the software is ju…

In the end they want to save on r&d / market research costs. In Ye Olde Times, Apple would go on their own and ask themselves "how can we make an improvement in the lives of our customers?"... the answer were iconic, revolutionary products (iPod, iPhone, earpods) that outright created entire device classes.

Now? The only thing in focus is rent extraction - App Store cuts -, recurring revenue and vertical integration. Anything not contributing to that gets atrophied (documentation, as mentioned, or Apple Server) or put on life support (essentially the whole rest of the ecosystem, including for all too many years pro-level hardware). Innovation? Why should Apple take the risk and improve their core product with features that won't get used? They're letting third party devs pick up the slack and buy up or clone the most successful things.

They're still better than Microsoft as they discovered that people are willing to pay a hefty premium for devices that have security and privacy first class members at the priority scheduling for new features (especially compared to the utter shitshow that Google has allowed Android to become by not cracking down on vendors), but innovation that doesn't give them a direct cash profit simply does not happen any more.

Re: On Apple's Piss-Poor Documentation

#207

Post by samatman »

corty wrote: post #145
orangefarm wrote: post #91

I can't get my head around why their documentation is so poor. They should have all the resources in the world to recruit people that have proven to write good documentation. If open-source projects run by volunteers can have excellent documentation (e.g. Vue), why can't Apple? Better docs mean a better developer experience which means more people want to (and are able to) develop apps for iOS which increases the val…

Apple developers are a captive audience, they will pay their annual hundred bucks and develop for iShiny no matter how crappy the docs are. There are just too many rich users and clueless PHBs demanding apple development to miss out. If those reasons went missing and Apple really had to compete for developer mindshare, docs would improve. Which leads to the solution: Quote a lot more for Apple development or don't de…

This answer doesn't really work for me.

iOS is Apple's bread and butter, and they make good money off those developers. It's in their cynical self-interest to spend the money to have the best documentation in the game, and it would even pay off inside Apple, with better APIs and better resources for their in-house teams to develop against.

It seems like a genuine institutional dysfunction. Apple has a culture of secrecy (which is necessary) and a result of this is deep siloing of teams. How this leads to documentation being such an afterthought is murky, but I suspect that's the cause, rather than merely being complacent about their walled garden.

Re: On Apple's Piss-Poor Documentation

#208

Post by vagrantJin »

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…

To be honest, was this helpful button is rather vague and I usually ignore it because it doesnt seem to be the right question or rather its a request for feedback I don't know helps me or not.

Re: On Apple's Piss-Poor Documentation

#209

Post by ljm »

wizzwizz4 wrote: post #181
pak9rabid wrote: post #146

Earlier quoted context omitted.

For all the hate it gets, I think the way PHP does their documentation is ideal. Easy to search for what you need, it recommends other, similar classes/functions, gives a good description of the inputs and what something is expected to return. Then, in addition to that, there's the user-supplied examples and commentary to help further clarify things. I really like the model they went with.

I concur. PHP is a horrible language, but I don't hate working in it. The documentation is the reason.

I concur and add that PHP has actually evolved quite nicely, and it's horribleness is merely an outdated meme. Java is still playing catchup to the stuff PHP has added in recent years.

Just because it was shit 15 years ago doesn't mean it's still shit now.

Re: On Apple's Piss-Poor Documentation

#210

Post by layoutIfNeeded »

alexashka wrote: post #148
auggierose wrote: post #33

I literally googled a few hours ago for "Why is Apple documentation so shit?" I mean, look at SwiftUI. Conceptually it's great, but it is also fucking buggy as hell, and I think one of the main reasons is that the developers themselves don't have good documentation available. The best documentation so far I found is this, but it's third-party: https://www.objc.io/books/thinking-in-swiftui/

SwiftUI is not great in any sense, other than looking great to people who've never written non-trivial software. When your criteria for 'great' is whatever 'content creators', 'software journalists' (email newsletter 'creators') and apple's marketing team pump out this week, 'great' is anything a marketing firm puts dollars behind that seems 'cool' and 'fresh' and 'hip', or is it 'dope' this week? It is quintessentia…

+1

And let me cue in my rant from a few weeks ago on the same topic: https://news.ycombinator.com/item?id=24947919

SwiftUI is “great” for a calculator demo or a to-do list app. Otherwise it’s just a gimmick, but Apple had gotten anxious about ReactNative and had to make something palatable for the webdevs... Although making SwiftUI mandatory for home screen widget extensions is very concerning, and on the long run they’re probably shooting themselves in the foot by pushing this buggy toy framework...

Post reply on HN