I always find Apple docs to be good and with right level of information. I do not agree with that article.
On Apple's Piss-Poor Documentation
151–160 of 348 posts
Re: On Apple's Piss-Poor Documentation
#152I've been a technical writer for ~8 years (3 at a startup, 5 at Gooble). I don't know Apple's situation but here's my guess: > Is the documentation team too small? (Likely.) Documentation is weird because there seems to be widespread agreement among developers about how lacking it is (and conversely I think it's safe to say how important it is for job success) yet technical writing is almost always understaffed, no m…
I'll admit that I'm pretty bad at formal documentation myself, but I've been wanting to improve that lately. So as a technical writer do you have any suggestions/links to material for learning the trade or even some sort of formal training courses for professional development that I can pass to my employer?
Re: On Apple's Piss-Poor Documentation
#153Look at the Elixir and Phoenix Framework if you want to see how documentation should be done.
Guides and introduction : https://elixir-lang.org/getting-started/introduction.html
Elixir reference doc: https://hexdocs.pm/elixir/Map.html
Phoenix reference doc: https://hexdocs.pm/phoenix/Phoenix.Controller.html
Re: On Apple's Piss-Poor Documentation
#154Earlier quoted context omitted.
That's a bogus claim! The MSDN documentation has always been freely available. The subscription service included all of Microsoft's software editions for development purposes and that's what subscribers actually paid for. The documentation of software packages, APIs, and driver kits was freely available online.
> The MSDN documentation has always been freely available No, it hasn't. It was originally available exclusively to subscribers, and only on CD. MSDN started before the web existed. Eventually , the documentation became free on the web.
That's a bit unfair. The web is what made it easy to publish at no cost, CD's still had mail and print costs associated so it made sense to send documentation with the software packages it... documented.
Re: On Apple's Piss-Poor Documentation
#155I always find Apple docs to be good and with right level of information. I do not agree with that article.
https://developer.apple.com/documentation/metal/mtldevice/14...
Here's Apple's documentation on creating a gpu command queue.
https://docs.microsoft.com/en-us/windows/win32/api/d3d12/nf-...
Here's msft d3d12
https://www.khronos.org/registry/vulkan/specs/1.2-extensions...
Vulkan for good measure.
Apple is CONSISTENTLY underspecifying APIs. The docs never refer back to comprehensive guides. They don't tell me the API constraints. They don't tell me the performance implications.
You may "think" Apple documentation is good, but honestly, it's bad and anyone that also programs for other platforms would arrive at the same conclusion.
Re: On Apple's Piss-Poor Documentation
#156Earlier quoted context omitted.
How are the "was this page helpful?" links working out on web.dev? Are you receiving useful feedback?
We get 1-5% response rates (which is normal; I've done this on a few sites now) but we have enough scale where we're getting enough feedback that I can use the data to identify the worst docs. The basic methodology is to prioritize the pages with the most pageviews + lowest helpfulness scores. Of course there's a risk that we're prioritizing our work based on data that isn't indicative of our overall audience and due…
Great, I'll definitely start indicating good/bad docs from now on. Thanks for you work!
Re: On Apple's Piss-Poor Documentation
#157Earlier quoted context omitted.
Rust and rustdoc (forget what it‘s called) have the same issues, sadly.
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.
Re: On Apple's Piss-Poor Documentation
#158Earlier quoted context omitted.
It’s because engineers don’t want to write documentation, and if you don’t force it this is the result.
A trillion dollar company should be able to hire some technical writers to embed into teams and write documentation as part of the process. It's just a lack of care when you have that amount of money.
Just hire Microsoft's people. Not even joking.
https://docs.microsoft.com/en-us/dotnet/api/system.string.su...
Re: On Apple's Piss-Poor Documentation
#159Earlier quoted context omitted.
It’s because engineers don’t want to write documentation, and if you don’t force it this is the result.
A trillion dollar company should be able to hire some technical writers to embed into teams and write documentation as part of the process. It's just a lack of care when you have that amount of money.
It's not really the size of the company. Anyone qualified to write good documentation can make better money, work on more interesting things, and advance their career by actually working on the code. Without a culture that rewards and values the work it doesn't get done.
Re: On Apple's Piss-Poor Documentation
#160I've been cursing the same problem with Objective C APIs for audio and some other stuff until I made a discovery: there's quite detailed documentation in comments in the API header files. Apple could generate documentation website from those comments if they wanted, but it seems that they don't want. Overview documentation would be nice, too, because the comments mostly cover details.