Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

On Apple's Piss-Poor Documentation

caseyliss.com

Post reply on HN
Print view View original

211–220 of 348 posts

Re: On Apple's Piss-Poor Documentation

#211

Post by dgritsko »

doyouevensunbro wrote: post #123
Ronsenshi wrote: post #107

Earlier quoted context omitted.

Already a thing: https://apps.apple.com/us/app/a-companion-for-swiftui/id1485... No affiliation. It's sad and a bit pathetic that trillion dollar company can't hire even one person to work on public documentation.

It’s because engineers don’t want to write documentation, and if you don’t force it this is the result.

I don't think this truism actually holds weight. Some engineers don't want to write documentation, sure. Maybe even most don't - but some actually do enjoy the process of writing good documentation, and they find satisfaction in creating knowledge artifacts that make their code easy to understand and use. It's not enough to just find these engineers, however - they need organizational support so that they have the right tools to create and share good documentation, and are appropriately encouraged to do so.

Re: On Apple's Piss-Poor Documentation

#212

Post by imtringued »

I think this old HN discussion is relevant because it shows that documentation is multifaceted and just one approach doesn't cover everything.

https://news.ycombinator.com/item?id=21289832

I have often seen people complain about auto generated documentation being worse than useless when that is not the case. It's not that the documentation is poor, it's that there is a complete lack of the other 3 kinds of documentation.

Re: On Apple's Piss-Poor Documentation

#213

Post by wlesieutre »

grimjack00 wrote: post #120
lostcolony wrote: post #86

Earlier quoted context omitted.

I've run into this more often than I can count with Java based things. "Just look at the Javadocs!" You...you mean the auto-generated API descriptors that have exactly zero usage information on them, and expect me to figure out how to piece things together just by type signature? That...that isn't how documentation works.

You mean you can't figure things out from "public Session getSession(String, String, String, String, String)"?

On the SwiftUI side, you might go digging in these docs for Previews, which are one of its biggest selling points: https://developer.apple.com/documentation/swiftui/previews

Take 30 seconds to read through that and the linked pages (that's all the time it will take) and see if you could figure out how to use a PreviewDevice to make your preview show a particular device.

It will tell you all the ways to initialize a PreviewDevice struct (from many different varieties of String), but you'll have no fucking idea what to do with that object.

And here's an actual code sample, via Paul Hudson:

  struct ContentView_Previews: PreviewProvider {
     static var previews: some View {
        Group {
           ContentView()
              .previewDevice(PreviewDevice(rawValue: "iPhone SE"))
              .previewDisplayName("iPhone SE")

           ContentView()
              .previewDevice(PreviewDevice(rawValue: "iPhone XS Max"))
              .previewDisplayName("iPhone XS Max")
        }
     }
  }
It turns out what you need to do is pass the PreviewDevice instance into a previewDevice modifier that you've applied to your view inside a struct adhering to the PreviewProvider protocol. I don't think this docs page even mentions that the previewDevice modifier exists, let alone how to put any of these pieces together to configure and display a preview.

You can find how to do this in tutorials elsewhere on Apple's site. But you can't find it in their documentation for Previews, because it's a bunch of automatically generated pages of function signatures with no explanation.

Re: On Apple's Piss-Poor Documentation

#214

Post by toxik »

seemack wrote: post #80
toxik wrote: post #15

Honestly, reading the headers is the only way to understand iOS, macOS, and iPadOS properly. I find that the older I get, the more _code is my documentation._ Particularly for things like Python's matplotlib, once you do more than put lines or scatter plots together, you _have_ to understand how the code actually works. Of course, that's difficult when all you get is header files, but still...

I get the mindset and am very much a read-the-code person as well but my go-to example for this kind of thinking is that reading the code in lieu of a written summary/guide, etc is like trying to understand a book where the chapters and paragraphs are mixed around. It's possible and the ability to do so worthy of pride but it's clear that a succinct summary in one place would be far easier and time-efficient. Not to…

Right, that’s the thing isn’t it—sometimes an abundance of documentation is actually not a good thing. matplotlib is a good example, its documentation fails to convey the common arguments and to what degree they are universal or not; reading the code is really the easier way in the end.

Re: On Apple's Piss-Poor Documentation

#215

Post by rocho »

wlesieutre wrote: post #2

I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!” Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me. So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medi…

> “Here’s the type signature, have fun!”

My experience with Go libraries in a nutshell. One of the factors that made me abandon that language for others that for me are much more productive.

Re: On Apple's Piss-Poor Documentation

#216

Post by ffhhj »

gentleman11 wrote: post #116
wlesieutre wrote: post #2

I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!” Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me. So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medi…

Unreal engine is like that, except with fewer third party tutorials. It’s getting better but the c++ docs are almost as bad as having nothing. Some of them only have comments like “maybe refactor this” as a description, and the community wiki was taken down recently too

Years ago I worked on the documentation for one of those big game engines. Previously as a "user" I suffered a lot with their physics system, and there was a big gap about its performance and best practices. After a long research in the source code and emails back and forth in the company I was able to fill those holes. My motivation came completely from within me, because absolutely no one in the company seemed interested on fixing the docs. It's the least important thing in most of these big companies.

Re: On Apple's Piss-Poor Documentation

#219

Post by yoz-y »

pornel wrote: post #47
wlesieutre wrote: post #6

Earlier quoted context omitted.

I will say that the WWDC sessions are well presented, and are a good place to start. But you can't use a video for quick reference, and you might be missing context from knowing how it worked the previous year to understand what the new enhancements are. Expect to dig into 2019 videos too. SwiftUI being new at least has the benefit that its sessions can't be any more outdated than that (yet). At most you're reconcili…

I hate that WWDC videos have essentially replaced docs. Videos have to be shallow, and code on slides has to be short. This medium is fine to sell an idea, and to give a high-level overview of how it works, but there's no way to include as much information as written documentation would. Here's a TED talk on Thorium reactors. Why aren't you running them yet?

On top of that they often contain pre-first-beta information so they are rapidly obsolete. Although the gist of the information is useful, the signatures and examples are not.

Re: On Apple's Piss-Poor Documentation

#220

Post by teknopaul »

sidlls wrote: post #157
Rotten194 wrote: post #150

Earlier quoted context omitted.

rustdoc has the ability to embed usage examples in the doc comments, and automatically test them. also module-level documentation is doable via doc comments in the module main file. rust doesn't force you to write good documentation, but the tools are all there and I often see great documentation for rust crates that was generated with cargo doc. For example the Rocket docs are full of code examples on both the modul…

That’s the barebones minimum, because in those contexts the examples are going to be relatively trivial. Often I find them to be no more helpful than the signature doc itself.

Even trivial examples that actually compile are better than none. because rust uses real code and markdown reading code and docs is the same thing in many cases, no need to even render to html, absolutely minimal markup noise. I love rust docs. Speaking from many years of using mostly poorly maintained javadocs and well maintained man pages.
Post reply on HN