dotnet
Update SmtpClient.xml
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).
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?
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 GitHubhttps://github.com/dotnet/dotnet-api-docs/pull/10010#issuecomment-2160288497, or unsubscribehttps://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:
:white_check_mark: Validation status: passed
| File | Status | Preview URL | Details |
|---|---|---|---|
| xml/System.Net.Mail/SmtpClient.xml | :white_check_mark:Succeeded | View |
For more details, please refer to the build report.
For any questions, please:
- Try searching the learn.microsoft.com contributor guides
- Post your question in the Learn support channel
![learn-build-service-prod[bot] avatar](https://avatars.githubusercontent.com/in/237442?v=4 "Published by a pub.dev verified publisher"){kind=small}
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. Seeing support requests doesn't necessarily imply that the package is bad. Seeing support requests doesn't necessarily imply that linking to the resource isn't helpful. Could it be it's just more common and therefore leads to more support requests?
Improving the documentation to add notes about the package being external / our support policy is all goodness. But removing the reference outright is just making documentation worse IMO.
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).