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

191–200 of 213 posts

Re: The Elephant at WWDC

#191

Post by logbiscuitswave »

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…

The link rot in MS documentation pages is simply maddening. If it’s not a 404, it’s completely different content that is only relevant to v.latest.

Just the other day I was trying to look up a behavior specific to an older version of Windows and the content was completely replaced with content only relevant to Windows 10 (and there was no real parity here to what I needed). I had to go to archive.org to find the information I was looking for from that page.

When I can actually find the docs I need, they are usually great but all too often just finding that content is frustratingly difficult.

Re: The Elephant at WWDC

#192

Post by gfxgirl »

travisgriggs wrote: post #162

Isn't the real time most software documentation started going down hill was as the internet became the primary way of distributing and updating software? When software distribution was tied to hardware mediums, it froze snapshots in time, and the documentation thereof could be snapshotted with it (to varying levels of success). Even needed to be. But once it all became primarily net based, it meant the software was a…

I think you're right. I also think there's often an attitude of "break things and move fast". Take a look at three.js, they break stuff every 3-4 releases which makes all the tutorials on the net out of date. They explicitly state they don't care one wit about backward compatibility.

It's also possible that it's not just that things are distributed on the net but also that the speed of development as accelerated. Some of the is undoubtedly due to the net (easier access to lots of resources/sample/libraries) as well as easier to collaborate and a ton more people doing it.

Re: The Elephant at WWDC

#193

Post by adambatkin »

shadowfiend wrote: post #81
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…

No. Modern day software strives to do this, but regularly falls short. To craft the abstraction correctly, you need to understand how it is to be used—this is its “whole”. The person writing the internals of the abstraction who does not understand the whole writes the internals poorly. They create a feature that breaks expectations. They optimize a code path whose unoptimized implementation is relied on for one reaso…

Yes, of course, when working on a piece of code (a low-level task), one should know where it sits within the bigger system. One needs to know all kinds of things about what lives both upstream and downstream, as well as some high-level architecture of the system as a whole. But the implication above (which I disagreed with) was that "good coding skills" (and thus a filter during hiring) implied "good documentation skills" does not follow from any of that.

Again: Code is always "low-level" (regardless of how much you do or don't know about the rest of the system) just like most API documentation. The complaint of the original article wasn't about API documentation, but about higher-level conceptual documentation being lacking. And just like not all "coders" may be able to design a large and complex system (though they may certainly be able to understand it) they also may be unable to document those high-level conceptual aspects of the system.

Re: The Elephant at WWDC

#194

Post by kaba0 »

amelius wrote: post #113
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…

Strangely, the best documentation I've seen so far has been PHP. The only reason: because developers could comment right below the documentation. It's like having StackOverflow right there, in the documentation page. (Note: I haven't touched PHP since 20 years or so, so not sure if it's still the case).

Especially the warnings like this ISO date function is not actually ISO-compatible :D

But I did like the comments idea

Re: The Elephant at WWDC

#195

Post by codeflo »

giantrobot wrote: post #166
codeflo wrote: post #160

Earlier quoted context omitted.

> The DocC tooling isn't going to be anymore effective than doxygen or other auto generated documentation without good architectural documentation. A function definition is nice but knowing you need to decombulate a frobnob before snizzlizing or that decombulation can only safely be done on the main thread is often more important. Explanations of design intent might be the most underrated kind of documentation. There…

Apple's architectural/design intent documentation is sort of hit or miss. The biggest issue (IMHO) with overall architecture documentation is too often it doesn't make it into written documentation. The key insights are sometimes the middle ten minutes of a WWDC keynote or presentation. If you didn't attend that WWDC session or pour over all the recordings you've missed that particular key concept. So you're then sor…

I see. Engineering blogs do fill some of that role in Microsoft’s stacks. This is not completely ideal either. Blog posts are frozen in time, and newer articles tend to only describe the deltas. So to get a current understanding, you also have to puzzle together various bits and pieces. But at the very least, blogs are easily searchable.

Re: The Elephant at WWDC

#196

Post by lmm »

giantrobot wrote: post #181
tylerscott wrote: post #169

Earlier quoted context omitted.

I completely agree. I never understood the argument of docs getting out of sync. If an organization prioritizes documentation then the comments are just as likely to stay in sync as the variables.

In-line documentation getting out of sync is a purely organizational problem. If documentation is valued by the organization inline documentation won't get out of sync. It's the easiest to keep in sync. It lives in the code it documents. It's in the same version control repo and the same version of the source building a binary can build the docs. If it ever does get out of sync with the code it's the most straightfor…

Documentation isn't automatically checked. Tests and sample code are a better alternative, since you can configure things to give you a build error if they ever get outdated.

Re: The Elephant at WWDC

#197

Post by lmm »

megameter wrote: post #175
travisgriggs wrote: post #162

Isn't the real time most software documentation started going down hill was as the internet became the primary way of distributing and updating software? When software distribution was tied to hardware mediums, it froze snapshots in time, and the documentation thereof could be snapshotted with it (to varying levels of success). Even needed to be. But once it all became primarily net based, it meant the software was a…

It speaks to the contradictory nature of software development as it's currently practiced, I think. "What does the software do?" "What do you want it to do? We can add that." "Well, I want to be able to access my old work in a few years, and maybe use it in another program." "I pinky promise that that will happen, and we will make that happen, after we get through all our other customer requests." It's not exactly a…

Most line-of-business software has always been more service than product, and I think we're right to embrace that. If you shrinkwrapped an accountant and sold them as they were, 5 years later they wouldn't be much good for anything. The computer is a bicycle rather than a taxi, it needs active involvement rather than passive use.

Re: The Elephant at WWDC

#198

Post by Cthulhu_ »

giantrobot wrote: post #140

From my perspective, I was in SWE at Apple for over a decade, their documentation started going downhill as iOS development ramped up. By the time they got to the yearly release cycle for macOS and iOS documentation was an afterthought. Most was generated with doxygen from inline docstrings. The reason I think the quality and quantity dropped was the internal schedules barely (or don't) leave enough time for the engi…

And I don't get it. A company like Apple could hire a small army of technical documentation writers who could go to town on it.

I do recall from my iOS development times that Apple's documentation and articles were really good.

Re: The Elephant at WWDC

#199

Post by salmo »

giantrobot wrote: post #140

From my perspective, I was in SWE at Apple for over a decade, their documentation started going downhill as iOS development ramped up. By the time they got to the yearly release cycle for macOS and iOS documentation was an afterthought. Most was generated with doxygen from inline docstrings. The reason I think the quality and quantity dropped was the internal schedules barely (or don't) leave enough time for the engi…

I don’t think any tool fixes that, as you alluded to.

I think a great example of this is the difference in docs between OSS Python projects.

Most include the auto generated Sphinx (or whatever) docs, with usually just a README level veneer. I quickly end up needing to wander the code. I swear any OAuth2 client library is fated into falling into this.

The great ones include a “quick start”, overall philosophy/architecture, sections on each sub component, common examples of “advanced usage”, and then the generated API docs (and source code). They let you dig deeper as you learn more, and hit more complicated requirements in your project. Click, requests, Flask, etc. are great examples of this to me.

Sphinx and other tools can be leveraged for all of that. But it does have to be written and maintained.

And not having access to the source (internally or externally) kills me for app dependencies. Sometimes I need to look just to understand the doc or see if I’m making a mistake or there’s a bug. Not trying to get into OSS philosophy, just the practical part for me.

Even the official Python docs can stink in places. The subprocess module replaces X, Y, and Z to be “simpler”, but if you want to know the method args, go read the docs on the thing it “replaces.”

I love “native” apps on my mac, and pay for quite a few. But I’d never try to make one. Even XCode is befuddling to me. It’s not an IDE, it’s an opaque RAD that makes me nostalgic for early 90’s Delphi.

Post reply on HN