Is this a problem in Windows? My dev work doesn't come near OS-specific issues, so I don't know.
The Elephant at WWDC
171–180 of 213 posts
Re: The Elephant at WWDC
#172This speaks to me. I’m not deeply involved in the iOS development world but I do a lot of webview-adjacent stuff so I keep a close eye on the WKWebView documentation. It’s a mess. Case in point: introduced in the new beta: loadSimulatedRequest: https://developer.apple.com/documentation/webkit/wkwebview/3... What does it do? Don’t know. I can make a few informed guesses from the name but I’m not sure if it’s maybe a p…
My latest one was the documentation for slicing up strings. All the example code for string.prefix() string.suffix() string.subscript() has code examples using arrays. https://developer.apple.com/documentation/swift/string/28948...
Those are automatically inherited docs (from Collection?), I think Xcode will actually tells you this but for some reason the website isn't.
Re: The Elephant at WWDC
#173I've been playing around with Swift/SwiftUI recently and while the documentation is still unclear in some areas, it is significantly better than the documentation for their Objective-C APIs was a few years ago when I was trying to make an iPhone app. Edit: Why is this downvoted? Do people really think the documentation got worse over the past few years?
I am not a fan of the SwiftUI docs, but I have yet to do a full-fat SwiftUI app. I was introduced to this app, which I think is a great help (I referenced it above): https://swiftui-lab.com/companion/
It seems like they've improved them quite a bit from what they used to be, but that app is great! Thanks for the recommendation.
Re: The Elephant at WWDC
#174One of the people who presented DocC used to lead both the rustdoc and docs.rs teams. You can see Ferris, the Rust mascot, on their desk. I think quality documentation can be written within the markdown that explains how higher levels concepts work. I see this in Rust all the time.
Off topic: I didn't know the Rust mascot was named Ferris. That's a lovely play on words.
I thought Ferris was named after ferrous oxide, which is the old name for Fe(II) oxide. But chemically, rust consists of Fe(III) oxide, or ferric oxide. So perhaps a more appropriate name would be Ferrick?
Re: The Elephant at WWDC
#175Isn'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 new problem that we keep updating software - "bells and whistles" is an old piece of hacker jargon - but there isn't a sense of definite publication now, because there are so many methods of blackboxing in the way, and that's been allowed to take place through the promise of "one more thing" and "surprise and delight" - we only really put up with it through a sense of increasing hype and spectacle. If you have a really firm grasp on what you want the computer to do, you can eliminate just about every application program.
Re: The Elephant at WWDC
#176Earlier 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…
To be fair to “Clean Code”, although it’s stance is clearly towards less (superfluous) comments, it recommends using doc strings to document intent.
What it recommends to just delete are comments like
var speed # the speedRe: The Elephant at WWDC
#177"nor are the skills of writing good documentation even vaguely similar to those for writing good code". I disagree. Vehemently.
Re: The Elephant at WWDC
#178Isn'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 worked on a project in the early 90s to figure out a way to distribute updated docs along with software updates. At the time, the software updates were shipped on CD, etc. We could ship the docs in WordPerfect AND Word formats. But that wasn't very palatable. We talked with WordPerfect about this portable document format thing they were working on (Envoy?). And we talked to Adobe about some sort of similar thing they had in mind. We could ship the document reader for Mac and Windows on the CD with the docs.
We also explored the idea of perhaps putting the docs as postscript files on an internet server with a ghostscript app and some instructions on how to ftp the files or something. That all seemed so close to right, but not quite feasible.
We weren't even considering the internet for software distribution. It was all an idea to provide our customers the latest and greatest documentation. But the internet was not established enough to let us refer customers there for practical use. And ghostscript was some hokey concept from people in some GNU movement or something and wasn't close to production quality.
Three years later we lived in a completely different world.
Re: The Elephant at WWDC
#179Earlier quoted context omitted.
Sometimes you have to look in the headers. I don't know why it doesn't get parsed into the docs. Here's the documentation for loadSimulatedRequest: /*! @abstract Sets the webpage contents from the passed data as if it was the response to the supplied request. The request is never actually sent to the supplied URL, though loads of resources defined in the NSData object would be performed. @param request The request sp…
That’s very useful information that would be very useful i the docs! Thank you. I’m a little confused as to how it differs from the existing method for loading data: https://developer.apple.com/documentation/webkit/wkwebview/1... but I suppose it allows for more customisability. Marking the existing one as deprecated would go a long way to solving the mystery. Assuming that’s even correct! This is where documentation…
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.
Re: The Elephant at WWDC
#180> have you ever heard of candidates for a software engineering post being selected by or for their ability to document their code? FWIW, when I’m involved in hiring, I absolutely consider this a major factor.
There's usually a vague "communication skills" aspect of interviewing, but it's not formalized. I'd be interested in hearing how you evaluate candidates for this.
Part of my team’s interview process is a small do-it-at-your-leisure at-home exercise in a repo we provide. Beyond the “solution”, we also get to see tests, documentation comments, commit messages, etc.