4 ms·
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
by no_wizard 7y ago
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-interface/controls/views?WT.mc_id=docs-dotnet-xamarin 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/ https://docs.python.org/3/
[1]https://developer.mozilla.org/en-US/ https://developer.mozilla.org/en-US/
- not_a_cop75 7y agophp, whether you like the language, or abhor it, has always had some of the most useful documentation, I've found.
- richardwhiuk 7y agoI disagree. See Example 5 in https://www.php.net/manual/en/security.database.sql-injection.php https://www.php.net/manual/en/security.database.sql-injectio... This is the recommended way to avoid SQL injection, using sprintf...
- wolco 7y agoSo 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?
- jontro 7y agoThe 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.
- adonese 7y agoSometimes 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 https://docs.python.org/3/library/argparse.html
- m463 7y agoargparse 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.
- carapace 7y agoPython's docs are infamously bad. And I say that as a Python fan. PHP's docs are the minimum standard, IMO.
- userbinator 7y agoI’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."
- no_wizard 7y agoThen why mark the documents as deprecated?
- userbinator 7y agoMS uses "deprecated" as a marketing term, but their backwards-compatibility commitment normally do not allow them to actually break things this way.
- jsmith45 7y agoFor 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 https://github.com/MicrosoftDocs/xamarin-docs