[Bug]: Confusing and wrong documentation on `is` vs `extend`

[artsiommiksiuk]

Describe the bug

I think the current documentation is very confusing and even a little wrong on is operator.

https://typespec.io/docs/language-basics/models/#using-the-is-operator

Usage of is instead of extends can't be recommended, just because is wouldn't allow you to specify new properties which are not of the base type, while extends allows.

In many languages, this would probably result in the same emitted code as is and it is recommended to use is Record instead.

It is missing additional context of that is is transfering decorators, while extends not.

Implementing own emitter this resulted in a confusion of properties completely stripped out by compiler without any errors when used is instead of extends.

Therefore I'd suggest remove at least is usage recommendation over extends at least. But generally to improve documentation, as it's been already more than a year since TypeSpec rename and half a year since release and documentation didn't improve match.

Reproduction

Checklist

• Follow our Code of Conduct
• Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion.
• The provided reproduction is a minimal reproducible example of the bug.