Update authentication section for clarity

[SirSpidey]

Addresses changes requested from reviewers to make the authentication section clearer as we migrate services to IAM.

Summary

• Update intro to authentication
• Move IAM to top of the stack of auth methods. Rename to just IAM
• Update getting credentials section
• Update Visual Recognition note
• Change headings to sentence case
• Update toc

cc @mkistler @ehdsouza @anweshan @mediumTaj

[SirSpidey]

@lopa, one thing missing from IAM here (and most other SDKs) that's available in the Swift SDK is an example of how to refresh the token. Not sure if that's needed in general

discovery.accessToken("new-accessToken-here")

[codecov-io]

Codecov Report

Merging #954 into develop will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             develop     #954   +/-   ##
==========================================
  Coverage      39.05%   39.05%           
  Complexity      1470     1470           
==========================================
  Files            580      580           
  Lines          14675    14675           
  Branches         840      840           
==========================================
  Hits            5731     5731           
  Misses          8610     8610           
  Partials         334      334

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f55fac7...641b845. Read the comment docs.

[lpatino10]

What's your opinion on that? We don't offer an exposed method to refresh a user's token, so if their token did expire and they need to use a new one, they would basically need to set the IamOptions again like the first time, now with the valid token.

I think that might be fine to leave out of explicit documentation but I could see the case for it.

[SirSpidey]

I don't have a strong opinion -- just noting that Mr. Kistler has it. We do have a link in the IAM section to how the process works. Because we're not supporting it, I think it makes more sense not to include it.

[lpatino10]

All looks good to me 👍 Thanks for the updates!