Clarifying recommendation for when to publish types to DefinitelyTyped vs bundled

packages/documentation/copy/en/declaration-files/Publishing.md から始め、特に 11～16 行目付近のガイダンスを確認し、その文言を issue で提案されている明確化と比較します。TypeScript プロジェクトと JavaScript プロジェクトの両方について、ドキュメントが組み込みの型と DefinitelyTyped に関するガイダンスを明確に区別できれば完了です。

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.