Azure Billing Metrics UX and docs update

[zmoog]

What does this PR do?

Update the integration UX and documentation to enhance:

• How to create and configure the required App Registration.
• How to use the scopes (subscription, department, and billing account).

Checklist

• I have reviewed tips for building integrations and this pull request is aligned with them.
• I have verified that all data streams collect metrics or logs.
• I have added an entry to my package's changelog.yml file.
• I have verified that Kibana version constraints are current according to guidelines.

How to test this PR locally

• Closes Enhance the UX and documentation for scope parameters being used in the collection of Azure billing usage details #3279

Screenshots

Settings

Documentation

[elasticmachine]

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS

Expand to view the summary

Build stats

• Start Time: 2022-09-22T20:39:58.313+0000

• Duration: 13 min 21 sec

Test stats 🧪

Test	Results
Failed	0
Passed	9
Skipped	0
Total	9

🤖 GitHub comments

Expand to view the GitHub comments

To re-run your PR in the CI, just comment with:

• /test : Re-trigger the build.

[elasticmachine]

🌐 Coverage report

Name	Metrics % (covered/total)	Diff
Packages	100.0% (0/0)	💚
Files	100.0% (0/0)	💚 2.65
Classes	100.0% (0/0)	💚 2.65
Methods	66.667% (2/3)	👎 -23.202
Lines	100.0% (0/0)	💚 8.671
Conditionals	100.0% (0/0)	💚

[colleenmcginnis]

👋 @zmoog thanks for improving the docs!

I took a first look at the changes, and I have some concerns about the order of the content. A few months ago we developed documentation guidelines for integrations. Part of the intention behind the guidelines was to gradually introduce more complex information to the reader as they are deciding whether or not to use the integration, setting it up, and customizing it for their use case.

For example, here's the thought process a reader might go through when visiting the integration docs:

1. The first thing they may want to know is what is this particular Azure integration for? (That should be covered in the Overview section.)
2. They probably have in mind what kind of data they want from Azure. We should describe that in a bit more detail next (in the Data streams section) so they can be confident that they are looking at the right Azure integration before getting into the details of implementation.
3. Then, once they are sold on this particular integration, we should be upfront about any requirements or limitations of the integration so they can again be confident that this integration will work with their use case (for example, knowing it will work with specific versions of a product). (This should be covered in the Requirements section.)
4. Then, once they are sure this is the right integration and that there are no deal breakers for using this integration with their systems, they are ready to set up the integration both from the Elastic side and the Azure side. (This should be covered in the Setup section.)
5. Finally, include additional information that is not necessarily required for all users to know, but may be very helpful to some. (This includes Reference content and Troubleshooting tips.)

If there's additional information to include that we think would be helpful to the reader, but does not fit into any of these categories (maybe "How it works" or "Cost"), we should talk about whether that should be added to the guidelines so other integrations can also benefit from those additions!

Let me know if you have any questions or concerns about reordering this content to align with the documentation guidelines (or if you would like me to make some changes to the order and commit them to this PR).

[zmoog]

Let me know if you have any questions or concerns about reordering this content to align with the documentation guidelines

Hey @colleenmcginnis, I am more than happy to align this doc to the guidelines! Consistency is king. I was aware it existed from you mentioning it in other PRs, but I didn't recall it when I started!

I will follow up with other comments.

Thank you so much for spending some time on the review!

[zmoog]

@colleenmcginnis, can I use the AWS docs as a reference [for minor details like headers, markdown syntax minutiae]?

[colleenmcginnis]

Yes! AWS would be a good reference. Though AWS has the central AWS integration and I don't think that exists for Azure, right?

We might be able to create a kind of "landing page" that is not associated with a specific integration, but contains an overview of Azure-related integrations if it would be helpful.

[zmoog]

Hey, @colleenmcginnis, thanks again for clarifying the purpose of the guideline; I think it's a great thing.

If there's additional information to include that we think would be helpful to the reade, but does not fit into any of these categories (maybe "How it works" or "Cost"), we should talk about whether that should be added to the guidelines so other integrations can also benefit from those additions!

I believe that both "How it works" and "Cost" sections do not deserve a spot at the top level of the guidelines: overview, data stream, requirements, setup, and reference work great.

In this new revision, I am experimenting with this approach:

• Moved "How it works" as a sub-section in Setup, so users can have an idea of what we are setting up at a glance. It's more of a visual overview of the result.
• Moved "Cost" as a sub-section of Requirement. I'm not 100% sure, but it may be a good fit in the section that should summarize the requirements and limitations. Like you are required to spend a little money to pull this data from Azure.

I also moved the "Settings" section at the end of the "Setup". The idea is to provide guidance about configuring the integration's setting page. Another approach would be to shrink this section by moving details in the field description on the setting page and leaving just a few field reference information, like the possible value for the endpoints ("Resource Manager Endpoint" and "Active Directory Endpoint").

@colleenmcginnis I'd love to know what you think. I'm open to suggestions and willing to move stuff around until we are both happy with the result.

[tommyers-elastic]

this is really great work - thanks maurizio

[colleenmcginnis]

I like how this content flows now. Thanks for aligning it with the documentation guidelines!

I left lots of comments/suggestions below, but most are relatively small. Let me know if you have any questions or concerns!

[zmoog]

@colleenmcginnis, do you think this PR needs more work on the docs?

[colleenmcginnis]

A few minor comments below, but after those are addressed this looks good from my side!