Clarifying recommendation for when to publish types to DefinitelyTyped vs bundled

Per #2804, I am creating a new issue to replace #2032 with renewed clarity and purpose.

When publishing types, there are essentially two standard ways to do so:

https://github.com/microsoft/TypeScript-Website/blob/b0e88bb679b78a6066e1734ffc22387550eaa8cf/packages/documentation/copy/en/declaration-files/Publishing.md?plain=1#L11-L16

Reading this, to me, "Otherwise" suggests that packages should only bundle their types if they were automatically generated.

This nicely covers two use cases:

1. Source is in TypeScript. Published package is compiled to JavaScript alongside type definitions.
2. Source is not in TypeScript. Package users independently publish and maintain types for the package.

I think a 3rd intermediate case is missing:

• Source is not in TypeScript. Code maintainer willing to add, maintain, and publish type definitions alongside source.

I've had passing conversations with maintainers that seemed to me to be under the impression that publishing manually created types separately was the preferred way to do it, seemingly because of this phrasing. Some even suggested doing this for TypeScript packages...

As far as I can tell, there is basically no downside to publishing accurate types along with source code, besides a marginal increase bundle size. The improved developer experience is well worth it and the types get compiled away for any real publishing. I would also think DefinitelyTyped would prefer if others did not rely on DT as it centralizes type issues in their respective packages and handles mismatched version issues intrinsically.

Suggestion for new phrasing

Including up-to-date types in published packages is always preferred. Bundling types improves developer experiences and reduces occurrence of common bugs and issues. If your types are generated by your source code, or you are keeping them up to date manually, we recommend you publish them with your published code bundle. Both TypeScript and JavaScript projects can generate types via declaration.

If you would prefer to not bundle your type definitions in your published package, we recommend submitting the types to DefinitelyTyped, which will publish them to the @types organization on npm.

If you do neither, any users of your package may still submit their own types to DefinitelyTyped.

Start with packages/documentation/copy/en/declaration-files/Publishing.md, especially the guidance around lines 11–16, and compare its wording with the issue’s proposed clarification. Done means the documentation clearly distinguishes bundled types from DefinitelyTyped guidance for both TypeScript and JavaScript projects.