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

201–210 of 213 posts

Re: The Elephant at WWDC

#201

Post by throwaway2037 »

p_l wrote: post #99
defaultname wrote: post #84

Earlier quoted context omitted.

"No, they've had lot's of documentation. That's not the same thing. " This kind of snotty reply is always interesting. I've been a professional developer for 25 years. For most of those years I was deep in the Microsoft platform. C++, Win32 API, DirectX, COM+/DCOM, OLE, automation, C# / .NET. For decades they've had exhaustive narrative documentation that would give huge backgrounders on everything. Architectural "ho…

arguably it's been the last decade that documentation from MS suffered, specifically around the time that their software stopped shipping with CHM&co files and started opening web pages. But they are quite actively rebuilding from the switchover. I still miss CHM.

The last sentence is a real gem. Zero trolling / Real question: What do you miss about CHM? My guess: It's a single package you can easily share and doesn't break once deployed (like a live website). :)

Re: The Elephant at WWDC

#202

Post by hamiltont »

auggierose wrote: post #117
hamiltont wrote: post #33

Passion comment: I'll second that most of Jonathan Levin’s books are outstanding, some of my favorite technical guides. Spent many years as senior dev for a custom Android ROM, yet Levin's book still introduced me to multiple other Android internals I had not yet looked into. Would happily pay 200-300 for his next Android book. Probably not the best books for a total beginner, but if you're already skilled and lookin…

Just tried to order the Levin books macOS/iOS books (wasn't even aware of them), but they don't ship to the UK ... Must be security restricted ...

WOuld not be surprised - he's reported piracy issues in past. FYI I've ordered all books by emailing directly to an email on the website. He replies with "send paypal to xx if you want digital only, send xxx if you want me to mail you a hardcopy". clunky relative to an amazon order but it gets the job done

Re: The Elephant at WWDC

#203

Post by giantrobot »

lmm wrote: post #196
giantrobot wrote: post #181

Earlier quoted context omitted.

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.

If you are changing some code that has inline documentation it's your responsibility to update it. If that is not your responsibility then it's an organizational failing. Keeping inline documentation up to date and clean should be part of the organization's coding style guidelines.

Tests are not documentation. They only test a very limited "what" or "how" and give no explanation of "why". If it's closed source software and you're only shipping a binary, the tests do not go with the binaries so they're meaningless to third parties. Sample code isn't much better. Without the organizational pressure to keep it in sync with the code it's demoing and "why" explanations it doesn't provide a lot of useful insight for third parties.

Re: The Elephant at WWDC

#204

Post by afavour »

aYsY4dDQ2NrcNzA wrote: post #185
code_duck wrote: post #179

Earlier quoted context omitted.

As I read it, the simulated response call doesn’t actually hit the URL, it just sets up the object like it’s going to then loads the data you supplied. Not sure when that’s useful since I’m not an iOS programmer.

Unit testing?

More likely for offline caching of web content. But unit tests too!

Re: The Elephant at WWDC

#205

Post by giantrobot »

codeflo wrote: post #195
giantrobot wrote: post #166

Earlier quoted context omitted.

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.

While blog posts aren't ideal they're (like you point out) better than nothing. But blogging goes completely against the grain of how Apple operates internally. The WebKit blog is a singular notable exception because that's a highly visible Open Source project. Even the free-form Q&A portions of WWDC sessions are rarely as frank as they should be in terms of usability.

No blogs is fine, that's just the corporate culture, but no blogs and no good up to date architectural documentation is a huge problem. It leads to cargo-cult understanding or complete misunderstandings by outside developers. Hell, it leads to cargo-cult understanding by internal developers.

Re: The Elephant at WWDC

#206

Post by itomato »

fomine3 wrote: post #186
brandonmenc wrote: post #14

I remember the documentation being pretty good up to and including OS X Tiger - back when Apple was still fighting for marketshare. I haven't tried to write anything for their platforms since then, specifically because the documentation is so poor. I don't have time to track down a bunch of old WWDC videos and hope that they approach something like usable minimum developer documentation when combined. I start that pr…

I wonder NeXT was better or bad for documentation.

Pretty good.

Documentation was part of the Framework, and accessible through Project Builder.

You could also package a Bookshelf and search from a Service.

Re: The Elephant at WWDC

#207

Post by 8bitsrule »

"Inside Macintosh" superb? I was puzzled and then disgusted when I saw that in stores, and realized the difference between Macs and the Apple II.

The manual for that machine was a masterpiece ... written for users. The 'revolution' ... obfuscating the OS internals, limiting access to the anointed ... was a tragedy. 'Killing Big Brother' my ass.

(It took me a lot of digging - in those pre-web days - to find out what magic numbers to poke, and where to poke, to turn the Mac serial port into a MIDI port.)

Anyway, I expected the 'elephant' to be the array of monopoly-busting legislation floating around the Congress right now. Popcorn ready.

Re: The Elephant at WWDC

#208

Post by p_l »

throwaway2037 wrote: post #201
p_l wrote: post #99

Earlier quoted context omitted.

arguably it's been the last decade that documentation from MS suffered, specifically around the time that their software stopped shipping with CHM&co files and started opening web pages. But they are quite actively rebuilding from the switchover. I still miss CHM.

The last sentence is a real gem. Zero trolling / Real question: What do you miss about CHM? My guess: It's a single package you can easily share and doesn't break once deployed (like a live website). :)

It was also fast, used quite minimal amount of resources even when there was a lot of diagrams included. Did I mention fast? Sure, generating an index could take a while - on PIO3/PIO4 drive with 486.

N.B. The first time I've read Time Management for System Administrators, it was CHM file I just copied onto my free (won in competition) Windows Mobile PDA.

Re: The Elephant at WWDC

#209

Post by lmm »

giantrobot wrote: post #203
lmm wrote: post #196

Earlier quoted context omitted.

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.

If you are changing some code that has inline documentation it's your responsibility to update it. If that is not your responsibility then it's an organizational failing. Keeping inline documentation up to date and clean should be part of the organization's coding style guidelines. Tests are not documentation. They only test a very limited "what" or "how" and give no explanation of "why". If it's closed source softwa…

Organizational pressure is a scarce resource, it's a waste to spend it on things that you can do with tooling. Keeping tests and sample code up to date involves more than just fixing compilation errors, sure, but the compilation error gets you reading and paying attention to the right piece of material.

Re: The Elephant at WWDC

#210

Post by aliasEli »

salmo wrote: post #199
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/architec…

The documentation of Delphi was pretty good. We received Delphi (1.0) on a Friday. I took the manuals home for the weekend to study. I started developing on Monday. On Wednesday we had an application with about 10 screens with access to a database and a working interface to a smartcard reader. Though Delphi certainly had its flaws, I still miss it for developing GUI programs.
Post reply on HN