[Documentation] Documentation confusing

[RihanArfan]

Please check all that apply

• [ ] typo
• [ ] documentation doesn't exist
• [x] documentation needs clarification
• [ ] error(s) in the example
• [ ] needs an example

Description of the issue

I've implemented Microsoft Identity Web (v2) into a .NET 6 MVC app that calls a Web API and I remember struggling and large fustration due documentation being conflicting, spread out, lacking and/or outdated. Once again, I've had to experience this while trying to find clear and straight forward documentation for using Microsoft Graph with Microsoft.Identity.Web for a colleague.

It seems like the main documentation for Microsoft.Identity.Web is spread between GitHub Wiki and Microsoft Learn, and the majority of it being outdated and for v1, when v2 has been out for a while. Guides for doing certain things are also unclear. I'm not sure what a fitting title for this issue is. First example is Microsoft.Identity.Web v2 introduced IDownstreamApi, but is only mentioned on the "news" page for v2, but not on Microsoft Learn or elsewhere on the wiki.

Another example, if I want to find documentation for how to call Microsoft Graph from a .NET MVC app. There are over 6 different guides/areas to look, none of which consistent. I understand this specific example might be more specific to Graph than Microsoft.Identity.Web, although I am trying to call it from an app that uses Microsoft.Identity.Web which involves Graph related things in the SDK.

• Tutorial: Access Microsoft Graph from a secured app as the user
• Tutorial: Access Microsoft Graph from a secured .NET app as the user
• Build .NET apps with Microsoft Graph
  • Turns out this is only console apps but title doesn't represent that
• https://github.com/AzureAD/microsoft-identity-web/wiki/v2.0#idownstreamapi
  • Page is hidden under release news and not clear it should be checked
• Calling a web API
  • Lacks much detail about the different options, the links just takes you to the second guide in my list
• https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/
  • The samples here don't use the new .NET minimal hosting model
• Web apps
  • Need to create a whole project from a template just to see rather than clear docs about it

Finally, parts of the wiki also seems to be unmaintained or outdated, with a lot of pages not touched for over 2-3 years. I do understand some things haven't changed, but I'm focusing on pages like Why use Microsoft Identity Web? which still have mentions to .NET Core 3.1 (EOL) despite .NET 8 being the current latest LTS.

I hope my tone doesn't come across as hateful and I mean no hate to anyone involved. Documentation is a big issue I've seen in the .NET ecosystem especially with this package and I hope that bringing attention to the problems I've faced can help improve the docs for others. 😃

[jennyf19]

Thanks @RihanArfan for the feedback. We are aware of the documentation gaps with Id Web and are working on addressing them.

[jmprieur]

Thanks for the feedback, @RihanArfan. I totally agree.