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

161–170 of 213 posts

Re: The Elephant at WWDC

#161

Post by psahgal »

TheOtherHobbes wrote: post #126
thesuperbigfrog wrote: post #13

Earlier quoted context omitted.

Apple's issue is that unless the code is open source, the documentation is the only thing available to the "outside of Apple" audience. If the documentation for the "outside of Apple" audience is not good enough without access to the source code, then developers feel it and the overall result is that Apple suffers as a platform.

Apple's issue is it doesn't seem to care. I'm going to speculate that improving the developer experience has a low status on the management hierarchy. So even if some people do care they're clearly not being given the resources to do anything about it. And the resources required are tiny. Technical writers are cheaper than developers, and you could hire a top team for $1m a year. Doubling that would still be a roundi…

I came to the same realization that Apple doesn't seem to care when I started learning how to build apps on iOS.

Coming from Android, I was used to having high level conceptual guides on the core building blocks of the framework. In the Android docs, I found detailed explanations of Activities, Fragments, Views, and other major components. It was relatively easy for me to get started, and the system was designed to be extensible. Google even published blog posts regularly, which I could use to learn more about design decisions.

When I made the jump to iOS, though, it was difficult to find parallel documentation for what I was looking for. At the time (this was 2015, mind you), I couldn't find anything beyond API documentation for ViewControllers, Views, Core Data, etc. Most of the major documentation existed on third-party sites like NSHipster. Not to mention code signing. I'm pretty sure I'm one of handful developers at my firm who knows the system well enough to explain how it works...and that was after 2 years of working in iOS full-time.

I doubt that Apple will prioritize the developer experience on their platform anytime soon.

Edit: In case anyone wants to see the difference...

- Google's guide on Activities: https://developer.android.com/guide/components/activities/in...

- Apple's guide on View Controllers: https://developer.apple.com/documentation/uikit/view_control...

Re: The Elephant at WWDC

#162

Post by travisgriggs »

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 always fluid, in motion. Imagine the tech writer approaching a developer now days:

"Explain how this works to me"

"Ok, right now, it works like this, but we're working on a revised version for next year..."

"Sigh. Ok, explain that to me too."

"You bet, but make sure and check back with me before you publish, because some things might change yet."

It's an irony, that the original dream of "the web", a distributed documentation system, is rendered ever instantly out dated in the realm of software because of the distribution models it eventually enabled. Unintended side effects I guess.

As a side anecdote, consider man pages for venerable established Unix commands. Now consider the man pages for newer Unix utilities. IME, the newer features are often under documented and require going to code portals to get detailed/up to date answers.

Re: The Elephant at WWDC

#163

Post by [deleted] »

adambatkin wrote: post #9
m12k wrote: post #2

> That’s not why they code, nor are the skills of writing good documentation even vaguely similar to those for writing good code. Strong disagree on that one. Writing good code is all communication - with the computer, with your colleagues, with your future self who doesn't remember how or why you did something. It's written knowledge transfer. Blocks of code, just like paragraphs of documentation, need to both fit i…

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…

[deleted]

Re: The Elephant at WWDC

#164

Post by Jetrel »

rleigh wrote: post #11
jtdev wrote: post #3

Earlier quoted context omitted.

A good coder does not a good technical document writer make.

I disagree. If a programmer cannot articulate their thoughts and ideas clearly, and cannot effectively communicate with others through writing, I would question whether they fully understand the concepts themselves, and whether they are actually a good programmer. Being able to write is a skill in its own right, but it's one which anyone can acquire with practice, and it's one which many programmers would benefit gre…

I completely agree. Of the various coders I've worked with over my career, I've noticed an astounding correlation between quality-of-writing and quality of code.

It becomes most curious with exceptionally talented people who are terrible communicators - they can engage with exotic and difficult pieces of code, but almost everything they write ends up being a trainwreck that nobody dares to use, nobody understands, and is typically riddled with bugs. Code is built to be used, and at the very least, you have to hand it off to other developers, or you're stuck maintaining it yourself. (In several cases like this, I've seen one of these programmers hand something off, and have others basically struggle to use it, and work around that by writing something much more rudimentary to replace it.)

I feel like a programmer needs to understand writing for the same reason a general needs to understand what it's like to be on the front line - even if they're doing very little of it themselves, they need a clear understanding of what needs to be accomplished and what the difficulties will be.

Re: The Elephant at WWDC

#165

Post by ghshephard »

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…

Depends on the version of Unix. OpenBSD considers documentation to be a first class feature of the operating system, and new functionality isn't considered ready for merging and release until the documentation is complete and high quality.

Re: The Elephant at WWDC

#166

Post by giantrobot »

codeflo wrote: post #160
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…

> 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 sort of feeling your way around some new technology and making it work but it's not as efficient or elegant as if you had the whole picture.

Because there's so little documentation time and Apple does not (as a rule) do engineering blogs or similar there's not a lot of of opacity into inner workings or designs. From the outside there's a lot more reading of tea leaves than you see for other platforms.

Re: The Elephant at WWDC

#167

Post by tablespoon »

codeflo wrote: post #160
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…

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

> Explanations of design intent might be the most underrated kind of documentation. There's so little of that nowadays in general, in any technology. Personally, I blame shortened attention spans, the death of programming books, and the rise of Stack Overflow. I'm not familiar with the Apple ecosystem, is it really worse in this regard than others?

I also blame dogmatic misunderstandings that have crystalized around "Agile." Maybe back in the day a some cookbook process specified a lot of useless documentation be created, but many people seem to have thrown the baby out with the bathwater and declared all documentation useless or not worth the effort.

Also some programming books are to blame. IIRC, the book "Clean Code" completely rejects comments because they can get out of sync with the code and therefore be misleading, and "clean code" should be self-documenting. However, all code can ever tell you is what is, it can never tell you why or what was really intended. Also, when you really think about it, method and variable names are comments too, which can get just as out of sync with what's really going on than a comment block.

Re: The Elephant at WWDC

#168

Post by mr_tristan »

SomeHacker44 wrote: post #58
mr_tristan wrote: post #35

Earlier quoted context omitted.

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.

I didn't say documentation shouldn't be written; writing is just one of many media types.

Many people do not stay focused with longer formats in writing. So adopting a variety of media is a good idea, especially for the fuzzier "conceptual" documents, as opposed to reference documentation.

And I say this as someone who prefers books. I've made the mistake of only using writing, and noticed about half of the team just never seemed to grasp the concepts. Example projects with really short videos helped them a lot.

Re: The Elephant at WWDC

#169

Post by tylerscott »

tablespoon wrote: post #167
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…

> Explanations of design intent might be the most underrated kind of documentation. There's so little of that nowadays in general, in any technology. Personally, I blame shortened attention spans, the death of programming books, and the rise of Stack Overflow. I'm not familiar with the Apple ecosystem, is it really worse in this regard than others? I also blame dogmatic misunderstandings that have crystalized around…

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.

Re: The Elephant at WWDC

#170

Post by phlakaton »

hug wrote: post #10
jtdev wrote: post #3

Earlier quoted context omitted.

A good coder does not a good technical document writer make.

I don't know why this is downvoted -- it's true. They are two very very different skillsets. I'm an ops guy, not a developer, and willing to hold my hand up and say that I suck at documentation. It's a deficit I recognise and work around: I have often paired up with someone who is better at documentation than I am, but less technically apt or possibly earlier on in their career than I am, because it's easier for me t…

You seem to have the writing chops to be a great documentation writer. What is holding you back?
Post reply on HN