Code snippets must be clearer on the version of the SDK

[maisarissi]

Microsoft Graph API reference docs and Graph Explorer provide code snippets given an HTTP call/scenario.
However, just by looking at the code snippet, it's impossible to know which SDK version it is compatible with.

We need to be clear which SDK version is supported in both platforms, Graph API reference docs and Graph Explorer.

Any suggestions on what it should look like? @RabebOthmani @lramosvea

[lramosvea]

@maisarissi, @jasonjoh and I had a discussion prior to our offsite about this. One of the things we discussed was having a support policy we can publish about versioning, which I think currently does not exist. We need to discuss this also with Seb and Vivian.

[ddyett]

@maisarissi @lramosvea do we still need to close on anything here?

[maisarissi]

We should have a new sentence highlighting the version used to generate the snippet:

@isvargasmsft @sebastienlevert @CarolKigoonya can you take a look at the suggestion and add any other thoughts?

[isvargasmsft]

I agree with adding a small flag with the version just for clarification. That could also promote upgrading to newer versions of the SDK.

[lramosvea]

We do need to add the SDK version used to generate the snippets.

[sebastienlevert]

This should be part of the snippet so it would also work with Graph Explorer. I agree this would deliver clear expectations for developers.

[andrueastman]

For the docs, we could probably do something like this. If we place a note inside the snippet block we run into the issue where using the copy functionality results in the user copying invalid code that may not compile.

Update user - Microsoft Graph beta | Microsoft Learn

The alternative is to use the option below with the text appearing as a code comment. This will also easily work with the Graph Explorer.

Update user - Microsoft Graph beta | Microsoft Learn

[sebastienlevert]

I like this option as it easily spans across all properties where we show snippets!

[maisarissi]

If we choose to go with the first option, which looks way better in our docs than just a comment line, would Graph Explorer be able to follow a similar pattern?

[sebastienlevert]

@maisarissi The first options seems like extra work for Graph Explorer as it doesn't support markdown currently IIRC.

[sebastienlevert]

Also, the fact that the version is copy / pasted is fairly interesting as it bring this context over to the developers IDE.

[maisarissi]

I agree with those points, however I feel that the code comment is "less visible", in a sense that, it's easier to ignore the information as opposed to the Note option that creates a block to draw the readers' attention to it.

What if we add the comment in the code snippet but in the docs we keep the Note as well?

[sebastienlevert]

I love this last version!

[isvargasmsft]

The note can be hosted in an include file that can be easily updated when we move to a different major version.

[sebastienlevert]

@isvargasmsft yes for the docs, not for GE though. So we need a solution that address both!

[maisarissi]

Ok! So I'll summarize our agreement:

• Have a include file with "Code snippets are only available for the latest version. Current version is 5.x"
• Use the include file to generate the Note section in the docs
• Also have the comment in the code showing the version so we can have the same information in Graph Explorer (this will duplicate the information for people in docs, but I don't think this is a problem)

The final version would be:

@sebastienlevert @isvargasmsft @andrueastman

[lramosvea]

I like having the note although not sure if this will look good on docs where we have many notes already and this might be a bit overwhelming for users. Let me share this with Steve.

[maisarissi]

Hey @lramosvea have you checked with Steve? We believe this will bring clarity to users.

[lramosvea]

Can't tag Steve here but did share this with him. Let me follow up and I'll get back to you.

[ddyett]

@lramosvea awaiting word of decision.

[lramosvea]

@ddyett @maisarissi after discussing this with the rest of the docs team, our recommendation is to just keep the comment in the code. We don't think the note needs to be added,

[ddyett]

@ddyett to move to global backlog. .NET complete but needs tracking for other languages.

[andrueastman]

Closing this for now given the available spec. This has been broken down into individual language issues below
CLI - #1935
Go - #1936
Python - #1937
PHP - #1938
Typescript - #1939
Powershell - #1940