News for hackers. Stuff that matters.
Re:Apple Developer Documentation Is Missing by no_wizard on Monday October 28, 2019 @10:28AM (#21377301)
I actually agree whole heartedly with the intentions behind this article. I find Apples documentation to be incomplete and not nearly as detailed as I think it should be.

I think that personally it’s not all that well organized either.

My minimum standard for good documentation has and always been Python’s[0]. While no documentation is perfect, I think they mostly get it right by providing good explanations and examples consistently throughout the documentation. I also like how it’s spilt up between modules and the code examples are routinely updated. I have found very little issue with Python’s docs. While it could definitely use more examples and and deeper content around asyncio in some parts (mostly around transports and protocols) on the whole its very good, to me it’s what all organizations should strive for at a minimum. I also want to call put Mozilla’s Developer Network (MDN)[1] as stellar, I reference and use it all the time and have genuinely been happy with it.

To be fair in assessments, I’ve also found links in Microsoft’s documentation that often link to things they have already marked as outdated or not going to be updated, or just don’t work like the GitHub links on this page:

https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-...

So I think a lot of documentation around the big platforms especially have a lot of work to do. This isn’t to say documentation is easy though. I sincerely hope that all this noise just means it becomes more of a priority. I know from experience that writing good documentation is hard and I don’t want this to come across like I’m faulting anyone in particular or organization in particular. I imagine with large and ever changing platforms it’s quite the challenge. I just wanted to point to some examples I believe get it right most of the time.

[0]https://docs.python.org/3/

[1]https://developer.mozilla.org/en-US/

Re:Apple Developer Documentation Is Missing by userbinator on Monday October 28, 2019 @09:19PM (#21383473)
I’ve also found links in Microsoft’s documentation that often link to things they have already marked as outdated or not going to be updated

IMHO that's usually a good sign --- that the API you're using is not ever going to change again. MS values stability and backwards compatibility far more than others (and in the past, that was even better) so "not going to be updated" means "this has become mature and stable, don't worry about unexpected changes."

Re:Apple Developer Documentation Is Missing by no_wizard on Tuesday October 29, 2019 @12:31PM (#21389028)
Then why mark the documents as deprecated?
Re:Apple Developer Documentation Is Missing by userbinator on Wednesday October 30, 2019 @09:42PM (#21404910)
MS uses "deprecated" as a marketing term, but their backwards-compatibility commitment normally do not allow them to actually break things this way.
Re:Apple Developer Documentation Is Missing by adonese on Monday October 28, 2019 @02:58PM (#21380289)
Sometimes i think python's docs are very verbose. Check for example argparse[1]!

GO docs are quite very neat and helpful though.

[1]: https://docs.python.org/3/library/argparse.html

Re:Apple Developer Documentation Is Missing by m463 on Tuesday October 29, 2019 @02:46AM (#21384723)
argparse is a heavily used but somewhat complicated library. I use it in every command line utility I write in python.

I usually search or scroll that page until I get to the feature I'm interested in. I like that it has plenty of examples.

Re:Apple Developer Documentation Is Missing by jsmith45 on Tuesday October 29, 2019 @01:17PM (#21389597)
For things like those broken links on docs.microsoft.com, you can file an issue (using the on page feedback tool, which generates github issues), or even send a pull request to the docs: https://github.com/MicrosoftDocs/xamarin-docs
Re:Apple Developer Documentation Is Missing by not_a_cop75 on Monday October 28, 2019 @10:35AM (#21377351)
php, whether you like the language, or abhor it, has always had some of the most useful documentation, I've found.
Re:Apple Developer Documentation Is Missing by richardwhiuk on Monday October 28, 2019 @01:59PM (#21379639)
I disagree.

See Example 5 in https://www.php.net/manual/en/security.database.sql-injectio...

This is the recommended way to avoid SQL injection, using sprintf...

Re:Apple Developer Documentation Is Missing by jontro on Monday October 28, 2019 @04:20PM (#21381186)
The article states this as the second bullet point "Use prepared statements with bound variables."

Reading the page I actually think this is pretty good for being language documentation.

Re:Apple Developer Documentation Is Missing by wolco on Monday October 28, 2019 @04:05PM (#21381033)
So bad docs because they list a way you don't approve of? They do list a number of different ways. They could have used intval() for example 4 because I prefer it but it doesn't take away from the docs or make them bad.

Do you have a method that makes sprintf with d value invalid?

Re:Apple Developer Documentation Is Missing by carapace on Monday October 28, 2019 @03:54PM (#21380908)
Python's docs are infamously bad. And I say that as a Python fan.

PHP's docs are the minimum standard, IMO.