-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update SmtpClient.xml #10010
base: main
Are you sure you want to change the base?
Update SmtpClient.xml #10010
Conversation
Remove reference to MailKit as we should not be recommending third party tools (that is up to the user to determine). We have also been receiving support cases for MailKit (because it is referred to in our docs).
We make similar recommendations in other places, e.g. https://github.com/dotnet/dotnet-api-docs/blob/main/includes%2Fdrawing.md#L12 |
MailKit should not be referenced in our docs as it is not a Microsoft product and is available open-source from Github.
We have received support cases on it - hence removing the references from our docs. Referring to it in our docs implies that Microsoft recommends this library. We don't - it is up to customer to choose.
From: Miha Zupan ***@***.***>
Sent: Tuesday, June 11, 2024 10:45 AM
To: dotnet/dotnet-api-docs ***@***.***>
Cc: David Barrett ***@***.***>; Author ***@***.***>
Subject: Re: [dotnet/dotnet-api-docs] Update SmtpClient.xml (PR #10010)
We make similar recommendations in other places, e.g. https://github.com/dotnet/dotnet-api-docs/blob/main/includes%2Fdrawing.md#L12
How come MailKit is more problematic?
-
Reply to this email directly, view it on GitHub<#10010 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AJMV7JNPB7WNJW52GYXQSDTZG3BIDAVCNFSM6AAAAABJD6ECI6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCNRQGI4DQNBZG4>.
You are receiving this because you authored the thread.Message ID: ***@***.******@***.***>>
|
The other examples I linked likewise include non Microsoft open source products. If it's really needed, should we instead add clarifications that these are external projects? Removing helpful references from documentation seems counter productive. |
It isn't a helpful reference if it generates support cases for us, as it is not something we support. It seems to generate more problems than it solves, so I don't agree that it is a helpful reference. I've tested the library - it is not intuitive, and doesn't seem to work particularly well. If customers want to use it, that is their call - but we shouldn't be recommending it. |
Learn Build status updates of commit 374624e: ✅ Validation status: passed
For more details, please refer to the build report. For any questions, please:
|
It's pretty common to link to third-party libraries from Learn, for example: https://learn.microsoft.com/en-us/dotnet/core/compatibility/core-libraries/6.0/system-drawing-common-windows-only#recommended-action. The general guidance for third-party links is here: https://review.learn.microsoft.com/en-us/help/platform/links-how-to?toc=%2Fhelp%2Fplatform%2Ftoc.json&bc=%2Fhelp%2Fplatform%2Fbreadcrumb%2Ftoc.json&branch=main#third-party-site-link-guidance. |
I'm not suggesting it isn't common to link to third party sites. I am requesting that this specific reference be removed as it is generating support requests for us, so isn't a benefit at all. Links to third party sites should only be included if there is a benefit. I am from the team that supports System.Net.Mail (or more accurately, deals with cases raised against it as it is no longer officially supported), and both EMEA and US have been receiving cases regarding Mailkit. If customers are having issues with Mailkit enough to raise cases to us, in my view that link is detrimental. |
It should also be noted that the link hasn't been added per the guidelines you reference (it is not clearly marked as an external site for one). |
There's a bit of a correlation/causation issue here imo. Improving the documentation to add notes about the package being external / our support policy is all goodness. Could we instead improve our processes of responding to such support requests? I'm surprised it's a meaningful burden to reply with a pregenerated boilerplate description of the product not being under our support. |
If we'd included links to more than one alternative that would be helpful and offer some choice. We haven't - we're specifically calling out MailKit as a suitable replacement (even though there are dozens of other third party solutions). If someone wants to do this investigation and add some useful information and alternatives, that would be reasonable imo. I'm not in a position to devote time to this. WIth regards to the support requests - developer support teams are very small. We do not want the requests for things we don't support raised at all, so the intention is to prevent such cases where possible. We already have boilerplate responses - it still takes time to handle these cases, and this time is wasted time (both for us and the customer). |
Summary
Remove reference to MailKit as we should not be recommending third party tools (it is up to the user to determine whether a third party tool is appropriate). We have also been receiving support cases for MailKit (because it is referred to in our docs).