Website Roadmap

[orta]

If you'd like to see and know more about the website infrastructure, there is an "updates thread" which digs into both what has been happening, and why.

My roadmap for the site + branding, influenced strongly by community feedback in microsoft/TypeScript#31983. Presented, roughly, as a linear priority list but in reality quite a lot are interlinked and so are being worked on concurrently.

• New Index Page
• Replacement for intermediary pages (samples etc)
• New Handbook Design
• New Playground v3
• Dark Mode
• TSConfig Reference
• Internationalization (roughly)
• Branding Page
• Search
• Mobile nav
• a11y audit

New Logo

Embrace the community logo by creating an official logo influenced by that version with some minor design tweaks.

Figma

This logo is then used throughout the re-designs below, and important for the branding page. We can provide official resources then ( see branding page at the bottom )

Re-designed Docs pages

Figma

• Brings it more in line with docs.microsoft.com
• Utilise the TypeScript compiler for error messaging and introspection
• Improve the navigation both in-page and for sections like the handbook
• Support switching code samples into playground sandboxes
• Design offers some useful extras:
• Shows contributors to the page, which should provide some incentive for more authors
• Shows when it was last updated

Redesigned Index page

Figma

Aimed at:

• simplifying TypeScript's messaging, making it easier for non-technical people to grok
• emphasize scope of DTS and how TS powers a lot of editor support for JS
• provide mode jump off points to docs, and understanding of TS release schedules
• showcasing work in TC39
• updating testamonials
• highlighting more talks from TS core team
• Have a design aesthetic which is closer to Microsoft's fluid UI system
• de-empathise the spec, given it's lack of updates

Add search to the site 🎉 Done

Super highly requested, algolia have reached out and will provide DocSearch for free over existing TS site as they do for other large OSS JS sites. I've worked with them before and it's been 👍

Fix some DNS issues

• You have to use www. today, that's a shame
• http links should be redirect to https to stop people thinking we've mis-configured the site
• Maybe a smaller link for playground URLs?

TSConfig Tooling

• Build a page which consolidates all docs on the TSConfig, maybe a playground-like experience as well as a full linkable reference. tsconfig-ui might be a good place for exploration there. See TSConfig Reference Overview  #103 for WIP
• Have sample TSConfigs for particular type of libraries
• Provide more extensive documentation about each flag inside the compiler, this can come from the new handbook too

I18n

Add support for non-English documentation #100

CLI Docs

• Re-examine tsc --help because:
  • Not all compiler flags are in there
  • It should probably link to this resource

Community Section

#5 has a lot of context for this

• Encourage more people connect offline
• Provide "blessing" for resources to have a more consistent way to have the community help each other
• Give ownership of sections to people who want to do work in the community
• Highlight books, mailing lists etc which lets people learn in alternative ways

Dark Mode for docs + playground

I'm getting daily pings about this, in part because it's become a meme but I think all popular consumer OS' now support light/dark modes and there's #90

Likely to come in with the redesigned pages.

Allow community localizations

Two big OSS JS sites have been doing community translations of content (react and Gatsby) and we can reuse their infra and ideas - gatsbyjs/rfcs#42

We can use tools like code-organizer-merge-on-green to allow others to handle merging PRs to languages they know

Convert from "everything in the handbook" to site sub-sections

Figma

Today almost all information about TypeScript lives in the handbook, ideally that would only be the language reference. We can kill the submodule and migrate it into the site (now that the site is OSS).

With sub-sections things like:

• Using JSDoc for Types
• Migrating from JS to TS
• Migrating from TS to TS Strict
• Working with Definitely Typed
• Using Projects to split up big repos
• Using TypeScript with build tools
• Shipping a JS Library with types
• React + TypeScript (it's one of the biggest TS eco-systems where they have little to official docs on how they work together)

We can also give ownership of some of these areas to contributors using code-organizer-merge-on-green

Better Resources for Compiler API users

• Audit existing documentation in the wiki
• Add JSDoc comments to anything missing them in the public interface
• Provide a full API reference via api-extractor Use API-Extractor to document the public API #80
• Maybe move resources into a sub-section on the site

Explore an interactive guide to basic + advanced types

The two pages Basic Types and Advanced Types represent a quarter of all traffic. Can we make something that consolidates the two, but isn't so dense?

Work to ensure multiple explanations of TypeScript concepts

We often describe concepts in terms of each other, and sometimes very technically, which can be tough for some learners.

• Provide playground example alternatives to intermediate and advanced type ideas
• Provide a glossary of TypeScript terms

Re-designed Playground

I added a lot of the features from the re-design in the current v2 of the playground, so it's mostly a design change now. But the revised sidebar would be nice. There's also ~20 open issues on the playground this would be a good time to hit some of those.

Figma

Split Playground into Playground + Sandbox

The TypeScript Sandbox is the editor part of the TypeScript Playground. It's effectively an opinionated fork of monaco-typescript with extra extension points so that projects like the TypeScript Playground can exist.

WIP build

This would allow us to embed the monaco-editor with a lot of playground features into documentation pages on request, as well as allowing external parties to have their own TypeScript powered API references with DTS files trivially.

Represents the end of the typescript-play fork.

New Branding Page

• Similar to Discord's in theme, provides all the logos and some light recommendations on how to use the logo.

• Gatsby's is good also

• Can provide recommendations for how folks can make and print their own stickers

[draem]

Epic.

[IgorHalfeld]

Awesome!!

[orta]

I shipped the branding page today, which makes this 100% done on the current roadmap.