Description
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