Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Website Roadmap #94

Open
orta opened this issue Oct 23, 2019 · 2 comments
Labels

Comments

@orta
Copy link
Member

@orta orta commented Oct 23, 2019

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 Logo

Embrace the community logo by creating an official logo influenced by it with some minor design tweaks. WIP and not fully confirmed, but close now.

Screen Shot 2019-10-23 at 10 51 53 AM
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

Screen Shot 2019-10-23 at 10 39 42 AM
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

Screen Shot 2019-10-23 at 10 11 32 AM
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 👍

Screen Shot 2019-10-23 at 10 45 41 AM

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

Screen Shot 2019-11-01 at 11 37 47 AM

  • 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 #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

Screen Shot 2019-10-23 at 10 38 22 AM
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 #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.

Screen Shot 2019-10-23 at 10 11 58 AM
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.

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

@orta orta pinned this issue Oct 23, 2019
@Draem

This comment has been minimized.

Copy link

@Draem Draem commented Oct 23, 2019

Epic.

@IgorHalfeld

This comment has been minimized.

Copy link

@IgorHalfeld IgorHalfeld commented Oct 23, 2019

Awesome!!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.