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

51–60 of 213 posts

Re: The Elephant at WWDC

#51

Post by the_only_law »

meibo wrote: post #48
bob1029 wrote: post #30

Conversely, I have noticed that Microsoft has been kicking some serious ass in the documentation arena lately. If you haven't taken a look at their stuff in a while, you would probably be shocked. Here's a high level overview of GC to give you an idea of how thorough these documents are now: https://docs.microsoft.com/en-us/dotnet/standard/garbage-col... After reading through all of those sections, I will have develo…

.NET documentation is incredible, not just for the language but also the APIs. It's such a joy to work with and even complex concepts seem to be explained very thoroughly. It gets a bit uglier once you cross into WINAPI, COM, etc., but Apple's is still not even close to being a match.

> It gets a bit uglier once you cross into WINAPI, COM, etc., but Apple's is still not even close to being a match.

I feel like .NET documentation has significantly improved. It wasn't that long ago when I had no idea how to find the documentation from the MSDN home page and had to rely on search engines, but outside I agree. Microsoft's documentation gets a bit rough. Most recently, I found the NDIS documentation unbearable, with broken links and links to 5.x versions. Additionally, I was trying to find the documentation on OLE, and google kept leading me to MFC specific stuff, which was not what I was looking for.

Re: The Elephant at WWDC

#52

Post by [deleted] »

bob1029 wrote: post #30

Conversely, I have noticed that Microsoft has been kicking some serious ass in the documentation arena lately. If you haven't taken a look at their stuff in a while, you would probably be shocked. Here's a high level overview of GC to give you an idea of how thorough these documents are now: https://docs.microsoft.com/en-us/dotnet/standard/garbage-col... After reading through all of those sections, I will have develo…

[deleted]

Re: The Elephant at WWDC

#53

Post by djoldman »

Generally you find good or great documentation where selling the product depends on it.

Apple is a hardware company, despite the money made from the app store. They don't lack for outside developers fighting bad documentation to make apps.

Poor documentation is not surprising at all; it's to be expected as there is little incentive to change.

Re: The Elephant at WWDC

#54

Post by alisonkisk »

defaultname wrote: post #44
bob1029 wrote: post #30

Conversely, I have noticed that Microsoft has been kicking some serious ass in the documentation arena lately. If you haven't taken a look at their stuff in a while, you would probably be shocked. Here's a high level overview of GC to give you an idea of how thorough these documents are now: https://docs.microsoft.com/en-us/dotnet/standard/garbage-col... After reading through all of those sections, I will have develo…

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?

Re: The Elephant at WWDC

#55

Post by cratermoon »

What's happening here is that Apple is only producing, weakly, reference materials. There need to be at least three other kinds of documentation.

The one the author focuses on that's missing is the explanatory type. The sort that's discursive and provides a broader understanding of the whys and hows of the code.

Two other kinds of useful documentation that would complete the package are tutorials, of the sort aimed at programmers just starting out with the material, and how-to-guides, for programmers that have a general understanding of the material but could use examples and steps to accomplish a specific goal with the system.

Re: The Elephant at WWDC

#56

Post by mooreds »

mooreds wrote: post #36

I have loved documentation for a long long time[0]. In my mind, as the developer continues to drive technology decisions[1], documentation in all its forms will continue to be a differentiator on par with functionality. Developers are learning all the time because their job is changing regularly, and good/excellent documentation is a competitive advantage. w/r/t the article, I feel like engineers should write documen…

Incidentally, if you are looking for a mental model around tech documentation, I haven't found a better one than this: https://diataxis.fr/ which discusses tutorials, how-to guides, technical reference and explanation.

Re: The Elephant at WWDC

#57

Post by alisonkisk »

z77dj3kl wrote: post #46
bob1029 wrote: post #30

Conversely, I have noticed that Microsoft has been kicking some serious ass in the documentation arena lately. If you haven't taken a look at their stuff in a while, you would probably be shocked. Here's a high level overview of GC to give you an idea of how thorough these documents are now: https://docs.microsoft.com/en-us/dotnet/standard/garbage-col... After reading through all of those sections, I will have develo…

Yeah, I've noticed this too. Most of the time when you look up something gRPC related, the first links are for some of Microsoft's gRPC documentation! gRPC is one of those projects that I'm not sure if Google really wants uptake or if it's just a dump as a means to open source other things they want uptake in (GCP client libraries, tensorflow, etc). The documentation is awful.

Idoubt google care if you use grpc for its own sake, unless adopting it for its own sake helps you migrate your important tech to google-preferred versions.

Re: The Elephant at WWDC

#58

Post by SomeHacker44 »

mr_tristan wrote: post #35
adambatkin wrote: post #9

Earlier quoted context omitted.

No. Modern programming languages and frameworks are explicitly designed so that you don't need to see how your code fits into the whole. That's the whole point of building abstractions, because it's too hard to keep all of the details in your head at one time. Writing code is generally concerned with the low-level details, which are hidden from other parts of the system (and that's a good thing). When you ask someone…

I've found that the higher-level docs often don't even need to be writing per se. I'd stick things like the 3-5 minute overview video, 30-60 minute presentations, and code examples in this type of category. Who maintains these? Most development teams I've met never bother checking the example code works. 99% of the time, they'll write up a presentation, once, click "record" on the video conferencing software, and eve…

Extraordinarily strongly disagree. Documentation should be first, best, and most thorough in written form. It is easily searchable, easily transferred, easily scanned for relevant sections.

Do anything else you want for your audienc3, but for me personally if there is not textual documentation, I will consider your system, software, library or whatever effectively undocumented.

Re: The Elephant at WWDC

#59

Post by valuearb »

traspler wrote: post #43

The way Apple talks about new developer features/systems seem like ads for very exclusive clubs sometimes. "If you are already doing this, you can do it here now and we show you some teases, talk to us if you want to know more". One example for me is ReplayKit... yes I don't know too much about Audio/Video but the little documentation there is it feels deliberately obfuscated and lacking. Better API level docs would…

New Kits are always tacked on, there are few overviews to tell you how an entire area works.

I once spent days trying to update old AV player code get close captions working with Vimeo streams on iOS, half that time was just trying to understand how captions worked in AV streams at all.

Every time something like AV gets a new set of APIs, Apple should update a detailed overview that explains we used to do things this way, then added these Kits to make it easier to do these things and you should only use them for these specific things now, because we have now have added these new Kits to address these new needs, or make this other thing easier, etc.

And I’m sick of watch videos. Give me a high level overview of the why and how of the managers, and in it link directly to detailed documentation pages, sample source code and pertinent WWDC videos so I don’t have to use my Google fu to figure out those links myself.

Re: The Elephant at WWDC

#60

Post by cratermoon »

jeremymcanally wrote: post #40

This post (while not wrong that the docs lack in a lot of areas) is written with apparent ignorance of how documentation is generated and published at Apple. Right now creating the code and docs are mostly decoupled. Having worked in the department where the docs are made, a tool like DocC is going to let the engineers who work on the code provide better docs to the Devpubs department so the authors there can stop wr…

If giving Apple developers tools that automatically generate useful API reference documents frees up the devpubs team to generate the other kinds of documents necessary, I'm all for it. If there's nothing but the API documents, DocC won't really address the issues.

> They’re a small but mighty team that’s constantly overwhelmed

Perhaps Apple needs to spend some money and effort there, but that sounds like a management problem.

Post reply on HN