Docs Meeting Notes, the v2 Handbook

[orta]

• Date: June 3rd, 2020
• Agenda
  1. Current handbook for v2 site 5-10min
  2. State of 'new handbook' repo vs v2 site 10min
  3. Long term goals 10min
  4. Open discussion: ~

Current Handbook

Link to the Prod handbook - v2 Site handbook index

• For v2 Handbook is split into three sections:

  • "Get started" - setting priors before teaching "e.g. learn JS"
  • "Handbook" - A-Z of being productive
  • "Reference" - topical deep-dives

• Sits along with:

  • "tutorials" - how do I use ts with x
  • "definition files" - example DTS and syntax overview
  • "config for TS" - it says on the box
  • "what's new" - release notes

New Handbook vs Current

• New Handbook - Full Table of Contents
• Site has all the same tools from the new handbook embedded

Goal: when you finish reading the handbook, you shouldn't be surprised by syntax

Missing from New Handbook + Advanced Types:

A page on JS Language Extensions

Popular extensions to JS which you are likely to see, but won't be in all apps

For example, covering: decorators, JSX, Enum

Dusty Corners

• Appendix: Dusty corners

Things which is possible to see in some codebases: Symbol, namespaces?

Extend classes page with TS additions

Highlight TS-specific class extensions separated from the main 'classes' docs

• Parameter Properties
• private /public / protected keywords
• abstract keyword
• etc

Where could @ts-ignore / @ts-expect-error live?

Could be how do I test my types? Or maybe as a part of showing 'ts always transpiles to JS'.

Import/Export

Could we have a doc around modules import/exporting, 'what is the common case'

• I installed x, how do I get to import it
• Bundlers
• esmodules coming

Misc Missing

• Polymorphic this (aka fluid interfaces)
• Global types shipped with TS Exclude, Extract etc (in Types from Extraction )
• tuple
• promise / async functions
• assertion functions
• Mapped types
• optional chaining

Goals once Site is Shipped

• Deprecate repos which arent the TS website: see Prepare the repo for archiving TypeScript-Handbook#1313

• Future sitemap ( use ctrl + mouse wheel to zoom, and hold space bar to drag around with mouse)

• Results from first feedback cycle - re:TS#31983

[gautamsingal]

@orta Can I contribute something in this?

[orta]

The repo (today) is https://github.com/microsoft/TypeScript-New-Handbook - that'll probably change once 4.0 is released, but you're welcome to provide feedback on where it currently is

[gautamsingal]

Thanks!