Next Steps for the TypeScript Website (April 2023 edition)

[RyanCavanaugh]

Next Steps on the TypeScript Website

TL;DR

We're taking this time to deliver a smaller, higher-quality, lower-cost version of the website that serves our needs while still leaving us time to do the work that we're best suited to do.

Key points:

• Declaring "issue bankruptcy"
• Shutting down the localization effort
• PRs will be handled

Background

For transparency: our team does not have any dedicated headcount for website content creation, design, or maintenance. Effectively, this means any work done for the website is in lieu of other work, much of which requires very specialized expertise. Conversely, a lot of the content and functionality on the website today is not differentiated in terms of the value it delivers. The TypeScript Playground, for example, largely replicates functionality found in VS Code or in other "Code Sandbox" websites, and it's slower and more difficult for us to deliver that functionality than it would be for someone who does web development as their full-time trade.

Microsoft web properties are rightfully held to high standards for compliance on many different axes, and we do not have adequate resourcing to maintain the current scope of the website while meeting those standards without taking away time from other higher-impact work. We plan to reduce the scope and scale of the website down to the minimum required to fulfill our needs.

Scope Reductions

Localizations

We were heartened to see the enthusiasm for the community-driven localization of the website and Handbook. However, the current state of localization leaves much to be desired for other reasons:

• We have no mechanism for keeping localizations up-to-date
• We have no mechanism for validating that localizations are correct
• Localization creates certain novel compliance obligations that are difficult or impossible to address without a fluent speaker of those languages
• Many pages are sitting "half-localized" with no actionable path toward 100%
• Observed traffic data for most localizations is extremely low

Mitigations:

• There have been previous language-specific efforts to localize Handbook content and these can now continue
• Machine translation should be "good enough" in the vast majority of cases, since we strive to write in simple sentences in our documentation. PRs to simplify language for the sake of more accurate machine translations will be accepted
• Our content has appropriate licensing to allow for this work to continue elsewhere, if desired

Playground Configurability

The goal of the TypeScript Playground is to allow TS users to easily try out TypeScript features and quickly examine the behavior of small examples.

The Playground isn't really intended for use for some of the other cases that it's currently being used for:

• Complex bug investigation
• Plugin hosting environment
• Comprehensive configuration testing
• Complex code sharing scenarios

Our long-term plan for the Playground is likely to eventually host a VS Code instance in this space. This will address many shortcomings with the current implementation (for example, certain kinds of snippets don't work in the Playground but do work in VS Code), and allow for a tsconfig.json-based configuration editing story.

Plugins are also impacted here. Switching to a VS Code instance means that the Playgound Plugin model will cease to function. However, VS Code has a rich plugin model already! We encourage anyone using Playground Plugins today to migrate to VS Code Plugins.

Mitigation: At this point, there's a virtually limitless list of other websites which embed some version of a TypeScript editing experience - codesandbox.io, codepen.io, playcode.io, and so on.

Bug Workbench

The bug workbench has been very handy, but its current location isn't ideal, since edits to it have to take place in the much larger embedding of the TS website. We'd like to move this to a community-driven open source project of some kind (i.e. outside the purview of Microsoft, basically). This should allow for faster iteration and more experimentation. I'll be reaching out to folks to try to find a home for this.

Other Low-Traffic Pages

There are a lot of dusty corners in the website that see very little traffic and are duplicative of other content. We'll be cleaning those out.

Issue Bankruptcy

We're going to declare issue bankruptcy on all open website issues. Please log a new issue if you have a critical problem (non-rendering pages, malicious links, accessibility problems, etc).

PR Backlog

With all this said so far, most of the open pull requests are still valid. We're going to work on merging/closing these with clarity and get down to a "zero open PR bounce". This will be done by having the weekly DefinitelyTyped maintainer also spend time handling website PRs. We expect this will take a few months.

PRs Going Forward

For additional clarity, we'd like to clarify what kinds of pull requests we can/cannot accept.

Acceptable PRs:

• Typo fixes
• Rephrasings for clarity
• Grammatical corrections
  • For consistency, our website is written in American English. Edits to change to other dialects will not be accepted.
• Technical corrections
  • Note that especially in the Handbook, brevity is a constraint, and the goal of the Handbook is not to outline every corner case of the language. Edits to explicitly call out trivia or edge cases will not necessarily be accepted.

Generally, we will not be able to accept changes which are likely to introduce compliance problems:

• Edits to raw HTML
• CSS changes, especially around color/spacing
• Infrastructure changes
• Header/footer/etc changes

[awxiaoxian2020]

Our content has appropriate licensing to allow for this work to continue elsewhere, if desired

If we want to continue our l18n, what is the setup recommended for the site? Now the site has many languages for l18n.

But if we continue, we only need a specific one in the specific community. For example, I only want to maintain the Chinese l18n.

[YexuanXiao]

Our content has appropriate licensing to allow for this work to continue elsewhere, if desired

If we want to continue our l18n, what is the setup recommended for the site? Now the site has many languages for l18n.

But if we continue, we only need a specific one in the specific community. For example, I only want to maintain the Chinese l18n.

It is a piece of unfortunate news that after so many years of software engineering born there is still not a good multi-person collaboration solution.

[DanKaplanSES]

PRs Going Forward

For additional clarity, we'd like to clarify what kinds of pull requests we can/cannot accept.

Acceptable PRs:

* Typo fixes

* Rephrasings for clarity

* Grammatical corrections
  
  * For consistency, our website is written in American English. Edits to change to other dialects will not be accepted.

* Technical corrections
  
  * Note that especially in the Handbook, **brevity is a constraint**, and the goal of the Handbook is not to outline every corner case of the language. Edits to explicitly call out trivia or edge cases will not necessarily be accepted.

I'm motivated to improve the documentation, but I'm not sure how much improvement is wanted. As a whole, this gives me the impression that the handbook is mostly stable.

For example, the right-hand side (i.e., the Table Of Contents) of the Narrowing documentation is indented after the Assertion functions section, and I see no reason why. If this is a bug, I gather that a PR to fix it would be considered.

On the other hand, and this is not a hypothetical, I was reading that same page and thought, "Maybe, where appropriate, the sections should explicitly say if they narrow the parent object or just the property." Such a PR wouldn't satisfy any of these bullet points. Does that mean it probably won't be considered?

One last example: a year ago I asked a question titled, How do I use tsconfig references for a project that has separate src and test directories? The official documentation could answer this question and this page is probably the appropriate place to do it by including a completely functional example at the end, or at the very least, the tsconfig.json files in their entirety. This might increase the page size by 20% or more. Does that mean it probably won't be considered?

[rxliuli]

Will the @typescript/sandbox module also be abandoned? I'm currently considering building a web editor based on it