Next Steps for the TypeScript Website (April 2023 edition)
RyanCavanaugh opened this issue · 18 comments
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
Great news! Not that I personally ever had a lot of problems with website, but ground-up rewrite usually produces a much better product.
Should we hope to get similar ticket on TS itself? :)
FYI, dropping the TS Playground without having some sort of redirection in place will break a lot of the third-party documentation (StackOverflow etc.) that you'll be relying more on now, as all the examples disappear. The Playground was also useful in accurately answering questions about which version an issue appeared or disappeared in when drafting issue reports on TypeScript; lack of that diagnostic information might raise the triage costs in the main repo.
I'm also not a big fan of brevity where it makes clear statements about how things work incorrect, as assumption that the code behaves as documented will lead to a LOT of wasted developer effort going down wrong paths to try to figure out why, and will probably result in even more issues in the TypeScript repo that you'll have to reject on the grounds that behavior opposite what's documented is fully intended and not-a-bug behavior.
We're not talking about removing the Playground entirely, or making categorically wrong statements in documentation.
Thanks for this detailed explanation of issues and intent!
Good to hear, but worth taking with a grain of salt.
We're not talking about removing the Playground entirely,
The clarification is useful, as the OP above wasn't clear on this (e.g. "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."). However, even if it's not fully removed but there are significant enough changes that links for the current/old format break and there's no redirection, external documentation and examples will break. Especially as the informational role of the website is reduced and the importance of external documentation is increased, I'd recommend planning for and including efforts to make sure those links still do something reasonable (like showing the code embedded in the URL at least).
With lots of external links into the non-Playground documentation too, it might be worth making sure the Internet Archive has a full copy of the site just before the revamp.
or making categorically wrong statements in documentation.
My experience with status quo practices is already having issue reports where actual behavior directly conflicts with documented behavior closed as the expectation is that developers will keep on top of reading 54K+ issues, including closed ones, to find out how actual behavior differs from what's documented. The overall message from the OP above makes it seem more likely this problem will get worse; my post above intends to caution against that. "X does Y" is fine but explicitly excluding the "except when it doesn't" from what is allowable in documentation can have the effects identified in my post above.
I'd recommend planning for and including efforts to make sure those links still do something reasonable (like showing the code embedded in the URL at least).
We're in the very early stages of any potential changes on that front. Out of anyone I think we're well aware of the value of keeping old links working. We have thousands of issues with playground repros, and of course the external resources you mention. So, keeping those working should be a goal, but this issue isn't the "playground planning issue", it's a notice that explains why we closed all of the issues and what kinds of things we will and won't accept.
My experience with status quo practices is already having issue reports where actual behavior directly conflicts with documented behavior
It's not in direct conflict with the documented behavior. You thought an invariant existed, but it doesn't, and the docs didn't imply it either. Fair enough - that happens to everyone from time to time when reading docs of any kind! But the documentation can't list every invariant that might exist but doesn't; for one, we can't even enumerate them if we try (people show up with new imagined invariants all the time), and even if we could, it would be an exhausting and unproductive list to read through. The same goes for novel misapprehensions. I can't write docs that will result in zero people ever making an incorrect inference, and I don't think anyone else can either.
The following content is courtesy of ChatGPT, which puts it better than I can:
We humbly request the kind attention of all those who may harbor an inclination to contribute towards the improvement of the phrasing of the description of Exclude, as we hereby present a verbose and protracted elucidation of our stance on the matter at hand. Should you feel inclined to offer your expertise and aid us in our noble endeavor, we would be delighted to receive your PR submission with open arms.
However, we do implore upon you, esteemed readers, to bear in mind that our objective is not to transmogrify the aforementioned document, which has been meticulously crafted to be comprehensible within a modest timeframe, into an overwrought, convoluted, and interminably long War and Peace-length treatise. Indeed, we must be vigilant and cautious, lest we inadvertently obscure the core message of the document with an excess of extraneous details and superfluous language.
As purveyors of the written word, we understand the importance of concision and clarity, and the impact these two attributes can have on the overall effectiveness of a document. We therefore implore you to exercise prudence and caution in your contributions, ensuring that your submissions are carefully curated and pared down to the most essential and pertinent details. It is only through a rigorous adherence to these principles that we can hope to produce a document that is both useful and accessible to all who encounter it.
In summation, we invite you to contribute to our endeavor with enthusiasm and fervor, but with the caveat that we maintain the utmost diligence and discipline in our approach, with an unwavering focus on concision, clarity, and brevity.
@RyanCavanaugh Is there documentation on invariants that do exist? That kind of documentation is usually called "formal semantics" or "language standard", and it also allows to figure out which invariants do not exist: they're not listed there. As far as I know, TS doesn't have any kind of specification, so your argument doesn't hold. There's nothing to make a correct inference out of.
Re: Playground requests, I've opened #2807
If anything, I would say you could scrap the rest of the website and JUST have the playground.
The fact that it ISN'T a vscode or a full sandbox is what makes it good and easy to use.
Otherwise, I would be using sandbox.io for everything.. but it's overkill.
The fact that it ISN'T a vscode or a full sandbox is what makes it good and easy to use.
@WORMSS, why Playground isn't full sandbox?
@WORMSS, why Pllayground isn't full sandbox?
I am unsure if you are asking why it's beneficial it is not a full sandbox? or asking how is it not a full sandbox?
Either way, this is not the location for that conversation.
If anything, I would say you could scrap the rest of the website and JUST have the playground.
I'm curious about this - no documentation at all? Or move it elsewhere (where) ?
No matter the resolution, I am glad that the Typescript team is taking initiative. I support it
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.
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.
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?
Will the @typescript/sandbox module also be abandoned? I'm currently considering building a web editor based on it