In the past year, the TypeScript team has focused heavily on making its documentation scaled, up-to-date and volumetric. One of the most important sections of this documentation is the guide, which is actually a guided tour of the TypeScript code you’ll find in most databases.

“We want this guide to look like the first recommendation you use to learn TypeScript.” – Microsoft

With the release of the updated website last year, Microsoft has included some small improvements to the guide, but the new version of the guide is what has become a “guiding star” for many of the new website’s features.

The new handbook project started in 2018 with an additional set of constraints on how Microsoft approaches learning:

Leave JavaScript Learning to the Experts

There are many great resources for learning JavaScript on the Internet and in books. We don’t need to compete in this space. The reference is intended to help engineers understand how TypeScript is built on top of JavaScript. This focus means that our documentation can make assumptions about the background and avoid explaining JavaScript functions from scratch.

This does not mean that Microsoft does not expect people of all skill levels to use this guide. For example, they added a new section to the site that introduces people to how TypeScript can compare to other languages, depending on their technical knowledge, as a precursor to reading the manual. You will see this in the documentation.

Learn gradually

Microsoft wanted to build concepts linearly on top of each other, avoiding TypeScript features that haven’t been explained yet. This limitation forced they to rethink the order and categories of language concepts. This learning curve made the first few pages a little difficult to create, but it does add value to the reader and encourage a style of reading from start to finish.

Let the compiler speak

If you’ve already used the TypeScript documentation since launching the new website, you might have noticed that Microsoft has code samples that provide inline context such as quick info and errors, and can even display .js and .d.ts output files …

As contributors to the tutorial, this means we need to be aware of when a TypeScript change affects the documentation. When we translate a website to a new version of TypeScript it also carries over to the manual, and if the results don’t match, it’s easy for us to see the impact and understand what changes we need to make.

What excites me is that Microsoft is using these tools to bring some of the best rich editor features to web pages and statically to epub/pdf files for reference. This technology can help your applications too.

For the reader, this means that all code samples on the site are up-to-date, accurate, and interactive.

Code for everyday cases

TypeScript has been around for 8 years and generally doesn’t remove features. Documenting all possible use cases and viable options for any concept has been moved from the domain of the directory to Microsoft ever-growing section of “help pages”. We think this should remove the distractions on the way to learning TypeScript.

While it may be interesting for some of us to learn about the history of JavaScript binding patterns, or how the more esoteric TypeScript options are changing code flow analysis, most people are either learning for projects from scratch or working in codebases with everything that has already studied.

These limitations helped us provide a more focused and accessible tour of the TypeScript language. We’re big fans (even if we might be biased).

Microsoft showcases all the old and new features, but they are all interconnected and presented in the same order. You never know what you might have missed. If you spot anything we’ve missed, feel free to leave a question on the Microsoft / TypeScript website.