121–130 of 213 posts
I do want to give a shout-out to this tool[0]. The "official" SwifUI docs leave something to be desired, so a developer wrote an awesome doc tool. I found out about this tool from an instructor at a class I took. [0] https://swiftui-lab.com/companion/
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…
Nope. They've always had a lot of documentation. It's often been crap. I've been developing for MS platforms off and on since Win3.1, and have constantly dealt with cycles of "knowing API function A requires you understand what an X is, linked to function B, which only discusses X in terms of function A.". They write a lot, but it's not good. It's like a Hollywood western set where your at just the fronts of building…
> 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.
One 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.
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…
> Microsoft has had superb documentation for decades No, they've had lot's of documentation. That's not the same thing. For decades it was very shallow with no examples. You'd get an enum list with a half sentence explanation. The last couple of years they've really upped their game. With detailed examples, explanations and even source in multiple languages. To me Qt's documentation was the benchmark, but the latest…
Win32 doc has always been good, back into the 90s. Some of the Sharepoint and Lync and when they were starting to open source all the things has been lacking. There was also that stretch where they axed all the QA department... Shudder...
> 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…
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.
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 rounding error in Apple's revenue stream. Multiplying it by 10 and introducing good management would be enough to make Apple's dev docs world-beating and legendary.
Apple could also run developer classes and camps online and f2f, publish its own books, create a regular stream of developer newsletters and tech updates, run forums that are actually useful, and so on.
The fact that none of this is happening at scale is... unfortunate. WWDC is a small plug in a big hole, and doesn't come close to meeting the community's needs.
This 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…
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…
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 beyond literally only detailing what the API does would be great.
Wasn’t the original Inside Macintosh supposedly a nightmare? Did it improve dramatically over the lifetime of (classic) MacOS?
The heyday was an app that had digitized all the documentation and iirc the code examples were in C. It had hyperlinks between pages. Quite nice pre web reference material.
Their code examples were also helpful, but things like low level double buffered sound recording or high performance animation was left as an exercise to the reader.
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…
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…
Apple quite frequently left important details and it took me few weeks to understand why the decoding code misbehaved in one particular case. With Microsoft I run into this only once and it was straightforward to fix. Note that in both those cases with Apple and Microsoft StackOverflow and similar sites was not helpful and even harmful retrospectively since that gave wrong direction to dig, but this is another story.
On the other hand Microsoft documentation was more shallower. If one knows roughly what to do, then things are OK. But by just reading one can not learn how to solve problems. Guides were not helpful, as those were at too high level.
Surprisingly with Apple, when they did described API, they gave helpful hints what to do next. Plus API was named more sensibly.
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…
> This kind of snotty reply is always interesting. I've been a professional developer for 25 years. I didn't interpret it as "snotty" (not beyond the norm for this forum, anyway). Could have been worded better, but charitable interpretation is an HN guideline. > There is some bizarre tendency in here for people to pretend that everything Microsoft does well they've only done well for most recent history, as if this i…
But a lot of things were already very good to excellent. I mean, one of the things you mentioned was developer friendliness yet the company has forever had industry leading developer relations. They've always had great documentation (there are going to be some developers who will still struggle and fail, but that isn't the fault of the documentation which can only drag them so far). SQL Server has been a great product for literally decades. NT was actually a great OS for the era and vis-a-vis its contemporaries. Microsoft has always been very "open" in fields where they are struggling. And on and on.
They did a lot of great things in the past along with bad things. And right now they're doing great things along with bad things. Every org is a mixed bag.