The Elephant at WWDC • Hacker News Board

Re: The Elephant at WWDC

#71

Post by gambiting » Sun, Jun 13, 2021, 4:10 PM UTC

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…

I'm a games developer working on some AAA xbox productions and I don't think I agree. My #1 impression with Microsoft documentation is that you run into a message "error occurred, click here to open documentation page", you click on it, only to be redirected to a 404 page or simply to MSDN's main website.

Like, yes, the pages that exist are usually very well written and detailed. But jesus christ, their links even just between MSDN pages are constantly broken, if you find an article older than 12 months you can be 100% certain nothing on the page will work when clicked on. It's like there is a wealth of knowledge there, but whoever is in charge of maintaining MSDN makes a point of redesiging the entire website every year and breaking literally every link in the process.

Re: The Elephant at WWDC

#72

Post by josephcsible » Sun, Jun 13, 2021, 4:12 PM UTC

the_arun wrote: post #64

Does `docc` works only for Swift? Could we use it for other programming languages? eg. Java

Basically every other programming language has already had something like this for a long time, e.g., Javadoc and Doxygen. Is there a particular reason you'd rather use DocC than these well-established alternatives?

Re: The Elephant at WWDC

#73

Post by BossingAround » Sun, Jun 13, 2021, 4:13 PM UTC

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…

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

I think this is an incredibly common situation. Personally speaking, I find that to be an excuse. If a woefully understaffed team of tech writers got the budget for 15 new tech writers, that usually wouldn't solve the problem.

The main issue is developers who don't believe documentation is highly important.

The "we generate documentation, so we're covered" is exactly the attitude I'd describe as highly unproductive. Of course that's great, but auto-generated docs are a small part of what should be your overall documentation suite. It shouldn't become the developers' excuse for not spending more time on documentation.

Tech writers will very rarely write docs from zero. I wouldn't even be surprised if the tech writers at Apple had no access to the source code, in which case they can't possibly write the docs from zero.

Re: The Elephant at WWDC

#74

Post by DenverCode » Sun, Jun 13, 2021, 4:23 PM UTC

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…

I am currently a year away from graduating and we haven't touched documentation once - simply commenting lines of code during DS&A.

Does anyone have any recommendations for resources to learn or is it simply reading through documentation akin to that Microsoft link and others like Stripe?

Re: The Elephant at WWDC

#75

Post by torben-friis » Sun, Jun 13, 2021, 4:23 PM UTC

>Those engineers are often selected at interview by posing them a coding challenge, but have you ever heard of candidates for a software engineering post being selected by or for their ability to document their code?

This was part of the code challenge at the company I'm currently working for. Checking how the candidate's solution was documented is a well defined part of the review process.

Re: The Elephant at WWDC

#76

Post by nextweek2 » Sun, Jun 13, 2021, 4:23 PM UTC

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…

> Microsoft has had superb documentation for decades

No, they've had lot's of documentation. That's not the same thing. For decades it was very shallow with no examples. You'd get an enum list with a half sentence explanation.

The last couple of years they've really upped their game. With detailed examples, explanations and even source in multiple languages.

To me Qt's documentation was the benchmark, but the latest documentation from Microsoft has really caught up.

Re: The Elephant at WWDC

#77

Post by ape4 » Sun, Jun 13, 2021, 4:24 PM UTC

gambiting wrote: post #71

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…

I'm a games developer working on some AAA xbox productions and I don't think I agree. My #1 impression with Microsoft documentation is that you run into a message "error occurred, click here to open documentation page", you click on it, only to be redirected to a 404 page or simply to MSDN's main website. Like, yes, the pages that exist are usually very well written and detailed. But jesus christ, their links even ju…

I've seen this. Also the search on the MSDN website is really bad. For some reason it never gets a reasonable result. I use google with site:docs.microsoft.com

Re: The Elephant at WWDC

#78

Post by throw14082020 » Sun, Jun 13, 2021, 4:27 PM UTC

JimDabell wrote: post #29

throw14082020 wrote: post #4

this article is saying how Apple DocC (the new documentation compiler revealed at WWDC 2021 this week) is not going to solve the problems Apple (and their developers) face. It has interesting examples. I think it will make documentation better, not because DocC is the perfect solution, but because it re-emphasises the importance of documentation because its new. It also gives developers at Apple a standard tool, was…

> It also gives developers at Apple a standard tool, was there such a thing before?. Yes, Jazzy, SwiftDoc, and appledoc already do this, plus whatever in-house tool that already existed at Apple before this (they have clearly been using something like this for the past ~15 years).

Aren't all the ones you mentioned all third party, so I would expect they won't be used at all internally. That makes me wonder if Apple uses open source much internally.

Also, DocC is integrated into Xcode, all the others tools could not be.

Re: The Elephant at WWDC

#79

Post by dafelst » Sun, Jun 13, 2021, 4:29 PM UTC

gambiting wrote: post #71

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…

I'm a games developer working on some AAA xbox productions and I don't think I agree. My #1 impression with Microsoft documentation is that you run into a message "error occurred, click here to open documentation page", you click on it, only to be redirected to a 404 page or simply to MSDN's main website. Like, yes, the pages that exist are usually very well written and detailed. But jesus christ, their links even ju…

Agreed, the Xbox documentation is hot garbage. They expect you to flip flop between the .chm file shipped with the XDK and online, but like you say the links are almost always broken. On the flip side though the private Xbox dev forums are awesome, I find them more useful than the docs.

Sony's PS4/PS5 docs also suck and are a giant pain in the ass to get to because they make you allow-list only specific IP addresses (a nightmare during the pandemic), but at least they are all in one place.

Re: The Elephant at WWDC

#80

Post by tonyedgecombe » Sun, Jun 13, 2021, 4:32 PM UTC

the_only_law wrote: post #51

meibo wrote: post #48

Earlier quoted context omitted.

.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 un…

Some of the older stuff seems to be getting worse. I was searching for information on Active Scripting and it appeared that documents I had used in the past had disappeared. I know nobody is implementing this from scratch but old code needs to be maintained.