81–90 of 348 posts
Moreover, Apple will also _remove_ documentation of API they are not favouring.
And it makes sense, Apple is such a monopoly it can afford to have zero documentation, application developer would still need to get users where they are.
But honestly, it's probably more that it's expensive to have good docs, so this job is being optimized out.
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…
Get ready for documentation subscriptions. I wish I were joking.
Currently it seems there is a never ending supply of developers ready to gamble years of their careers on Apples Terms & Conditions, and while these same people usually eventually realize that there's ultimately no money to be made, they are replaced with a new generation seeking an AppStore paved with gold. Until that stops, the docs will stay piss-poor.
While I have often used a Mac for development and enjoyed it, I don't often actually develop anything for macOS or iOS because, well, why would I risk my livelihood on Apple's whim? They regularly destroy developer's lives with no thought or consequence.
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…
How are the "was this page helpful?" links working out on web.dev? Are you receiving useful feedback?
Earlier quoted context omitted.
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 hate that WWDC videos have essentially replaced docs. Videos have to be shallow, and code on slides has to be short. This medium is fine to sell an idea, and to give a high-level overview of how it works, but there's no way to include as much information as written documentation would. Here's a TED talk on Thorium reactors. Why aren't you running them yet?
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 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 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…
> 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.…
With Chrome DevTools (I wrote/maintained pretty much all the official docs for about 3 years) it was a bit easier because I had a huge repository of direct user experience to draw from: the thousands of Stack Overflow questions about DevTools
Earlier quoted context omitted.
How are the "was this page helpful?" links working out on web.dev? Are you receiving useful feedback?
We get 1-5% response rates (which is normal; I've done this on a few sites now) but we have enough scale where we're getting enough feedback that I can use the data to identify the worst docs. The basic methodology is to prioritize the pages with the most pageviews + lowest helpfulness scores. Of course there's a risk that we're prioritizing our work based on data that isn't indicative of our overall audience and due…
Plus, the examples are almost always broken and don't compile. Broken samples and videos are horrible ways to teach anything.