search

MicrosoftDocs / feedback

📢 docs.microsoft.com site feedback
https://learn.microsoft.com
Creative Commons Attribution 4.0 International
239 stars 160 forks source link

Java Documentation is an incomprehensible alice in wonderland rabbit hole #3587

Open CaymanTurtleBeach opened 3 years ago

CaymanTurtleBeach commented 3 years ago

Describe the bug A standard for Java programming is Javadoc. If MS is going to pretend to provide Java libraries, it needs to provide DIRECT links to Javadocs for Java products.

I have now wasted over an hour, looking specifically for the V12 API Javadoc, to help me decide whether to update one module that currently uses V8.x storage libraries, as a precursor to updating a lot more code, mostly in Azure functions. Specifically (as an example) the readme at azure-sdk-for-java/sdk/storage/azure-storage-blob/README.md' has a link at the top labeledAPI reference documentation`. But it goes to some generic page with NO specific API documentation - just more bloviating about Getting Started, pre-requisites, etc. etc. WHICH ARE MOSTLY COVERED in the README I just left, along with a bunch of linked phrases, some of which by their language might have a chance of arriving at actual API documentation. BUT THAT IS HOW I HAVE WASTED AN HOUR. Apparently words at MS do not mean what a marginally educated nuclear engineer from the University of Virginia and graduate work at Carnegie Mellon University, native English speaker, thinks they mean.

To Reproduce Steps to reproduce the behavior:

  1. Go to `azure-sdk-for-java/sdk/storage/azure-storage-blob/README.md'
  2. Click on 'API reference documentation'
  3. Tell me where on that page there is a direct link to documentation directly for the API - I clicked a link that says API reference. I expect an API reference (i.e., Javadoc).
  4. As a related aside, somewhere down the rabbit hole I stumbled on an API search box. What an abysmally useless page. Of the 1000s of API calls that I deal with on a daily basis, many of which have similar names. I will happily pit my short-term memory against anyone's, but if I need to find a specific API it would be only pure luck that I happened to remember the right sub words or phrases that the feeble search engine which appears to back up that search box would recognize to produce something useful.
  5. See above

Expected behavior A clear and concise description of the Java storage library API

Screenshots The presumably top level gospel for the Azure Storage Blob client library for Java: image . The page that API reference documentation links to: image

WHY SHOULD I HAVE TO READ ANOTHER PAGE OF EXTRANEOUS INFORMATION and try to guess what link will really take me to the documentation I am looking for. Incredible. THIS is what I am looking for - and I believe I am on solid ground in saying that this is content and style that is the standard for Java. https://azure.github.io/ref-docs/java/ I do not remember how I originally found this link, but going to just azure.github.io yields a bunch of what appear to be marketing rather than technical options, and going down 3 levels before giving up produced nothing that suggested Javadoc for V12 storage.

Desktop (please complete the following information):

Smartphone (please complete the following information):

Additional context Add any other context about the problem here.

welcome[bot] commented 3 years ago

Thank you for creating the issue! One of our team members will get back to you shortly with additional information. If this is a product issue, please close this and contact the particular product's support instead (see https://support.microsoft.com/allproducts for the list of support websites).