Hi there 👋 Thank you so much for trying to improving the current docs. @DanielRosenwasser asked for feedback on Twitter and here are my 2 cents about the "Basic" chapter, which is the only one I could read so far.
Disclaimer: I don't know how this handbook is embedded in the new website, but I assume that it will be the very first touching point for everyone who wants to learn TypeScript.
Introduction
I needed to re-read some sentences in the current introduction. Maybe it was because I'm not a native english speaker or that in some sence the introduction was already deeper and more complex than I'd expected and I tried to figure out what is the goal of the introduction while reading it.
I think the goal of the introduction is summarized in the last two sentences:
JavaScript only truly provides dynamic typing - running the code to see what happens.
The alternative is to use a static type system to make predictions about what code is legal before it runs.
Maybe the whole introduction can be trimmed down to one example which illustrates this statement. I think the flip example would be sufficient already.
However there were other parts I missed in the introduction.
A small greeting: "Hello everyone!"
A small sentence about what TypeScript actually is. When I search the documentation for TypeScript it's first mentioned as "That's what a static type-checker like TypeScript does." I think this is already a good statement: Is TypeScript a type-checker? Is it a language? Is it both? If yes, is it even more? etc.
A statement about the goals of this handbook. Is is about learning the language? Is it about learning how to use the compiler? Something else?
A statement about how this handbook is structured. What previous experience is assumed? (e.g. knowledge about JavaScript, npm, the terminal) What are the chapters? Can they be read in any order?
Some meta information about how to get help. "Feeling lost? Click here.", "Found a typo? Report it here." and so on.
Goals
My personal goal of this handbook is to have the resource I can give to people who are new to TypeScript to learn the language.
If often saw people with previous programming knowledge, but without experience to TypeScript to either
come to an already existing TypeScript project or
start with people already familiar with TypeScript (and how to setup a TypeScript project) a new TypeScript project where they needed to use TypeScript, but wasn't in charge of setting up the project.
I personally would wish to not see any advice about how to download, configure and use tsc in the "Basics" chapter. Finding out about command line flags like --noEmitOnError would be something I'd cover in a later chapter. (Or maybe in a completely different handbook - the tsc handbook?) I'd love to see handbook which doesn't rely on additional tooling in the first chapters and would leverage embedded playgrounds for all examples, so someone who wants to learn TypeScript doesn't have to leave the browser.
I also assume that we still have something like "TypeScript in 5 minutes" (or maybe even "TypeScript in 5 minutes with tsc", "TypeScript in 5 minutes with babel", "TypeScript in 5 minutes with webpack", "TypeScript in 5 minutes with parcel", etc.). If we state our goals of the handbook in the introduction, we may also state non-goals (like introduction to specific tooling) and could navigate people who are interested in this topic to a different ressource.
I'd also introcude people to the general design vision of TypeScript here, so I can refer to them in later section. E.g. things which are currently listed at the end of the "Basic" chapter like "Type annotations never change the runtime behavior of your program."
Define common terms
Similar to how the introduction should define the term TypeScript I'd also explictly try to define certain terms which may are unknown, but used a lot. A good example is ECMAScript. The first time its used its just called "the ECMAScript specification" with a link to the spec, but not a concrete explanation. Later it's used in "Type annotations aren't part of JavaScript (or ECMAScript to be pedantic)" - maybe it would be good to explicitly explain when what term is used beforehand. The next oocurence is this:
Template strings are a feature from a version of ECMAScript called ECMAScript 2015 (a.k.a. ECMAScript 6, ES2015, ES6, etc. - don't ask). TypeScript has the ability to rewrite code from newer versions of ECMAScript to older ones such as ECMAScript 3 or ECMAScript 5 (a.k.a. ES3 and ES5).
I'd try to simplify this a little bit and be more straightforward. Something like this:
The language JavaScript as we commonly call it has a formal specification which is called ECMAScript. You can find the complete specification here. Most of the times both terms are interchangeable and thoughout this guide we'll use JavaScript, with one exception: As the language evolves and new features are added also new versions of the ECMAScript specification are created. These versions original used a major version number )like ECMAScript 3 or ECMAScript 5) and later switched to a version scheme using the current year (like ECMAScript 2015). In general we abbreviate these versions as ES3, ES2015 and so on.
But mabye this can be even dropped in the "Basics" chapter completely, when we move tsc and the downleveling section to a later chapter.
Avoid noise and use a neutral tone
Things like:
Tada! Wait, "tada" what exactly?
...to be pedantic
a.k.a. ECMAScript 6, ES2015, ES6, etc. - don't ask
By default TypeScript targets ES3, an extremely old version of ECMAScript.
A friendly casual tone is nice, but some filler make it harder to read the documentation. Some of these examples could be dropped completely (imho) and others can be rewritten like the last one.
By default TypeScript targets ES3, which is the oldest version of ECMAScript which TypeScript supports.
Be as opinionated as possible
In some cases that is already done quite well ("it's best not to add annotations when the type system would end up inferring the same type anyway"), but maybe it can be taken even further.
E.g. if we would embed playground examples and would not introduce tsc so early, we could also build every example in a way that they use --strict by default. In that case I wouldn't even explain that there is a hidden --strict setting in the background, but I'd write the complete handbook using this best practice and I'd just in a later advanced chapter tell the reader, that there are actually looser and more dangerous configurations possible.
That makes reading the introduction leaner (less explanation about configurations) and you automatically teach good practices.
Avoid uncertainties
For that I think I just found one example:
In this case, there was very little for TypeScript to transform, so it looks identical to what we wrote.
What's very little and looks identical in that case? I stumbled over this question and couldn't read further, because I first had to answer it in my head. Was there something transformed I couldn't see/find or are they identical (even though just for this particular example)?
A different approach how to explain a type checker
Currently the type checker is explained like this:
"We've been talking about type-checking, but we haven't yet used our type-checker. Let's get acquainted with our new friend tsc..."
"writing our first TypeScript program"
"now let's type-check it"
"there were no type errors"
"But check again - we got some file output instead."
Then somethind about transforming files...
Then we introduce a type-checking error and try it again.
Maybe we can find a more straightforward explanation which doesn't touch tranforming files in the middle of the explanation. That would probably be easier with embedded playgrounds as well.
I hope the feedback is valuable and doesn't sound too negative. Thank you very much for trying to improve the documentation. Feel free to close the issue immediately 🙃
Hi there 👋 Thank you so much for trying to improving the current docs. @DanielRosenwasser asked for feedback on Twitter and here are my 2 cents about the "Basic" chapter, which is the only one I could read so far.
Disclaimer: I don't know how this handbook is embedded in the new website, but I assume that it will be the very first touching point for everyone who wants to learn TypeScript.
Introduction
I needed to re-read some sentences in the current introduction. Maybe it was because I'm not a native english speaker or that in some sence the introduction was already deeper and more complex than I'd expected and I tried to figure out what is the goal of the introduction while reading it.
I think the goal of the introduction is summarized in the last two sentences:
Maybe the whole introduction can be trimmed down to one example which illustrates this statement. I think the
flipexample would be sufficient already.However there were other parts I missed in the introduction.
Goals
My personal goal of this handbook is to have the resource I can give to people who are new to TypeScript to learn the language.
If often saw people with previous programming knowledge, but without experience to TypeScript to either
I personally would wish to not see any advice about how to download, configure and use
tscin the "Basics" chapter. Finding out about command line flags like--noEmitOnErrorwould be something I'd cover in a later chapter. (Or maybe in a completely different handbook - thetschandbook?) I'd love to see handbook which doesn't rely on additional tooling in the first chapters and would leverage embedded playgrounds for all examples, so someone who wants to learn TypeScript doesn't have to leave the browser.I also assume that we still have something like "TypeScript in 5 minutes" (or maybe even "TypeScript in 5 minutes with
tsc", "TypeScript in 5 minutes withbabel", "TypeScript in 5 minutes withwebpack", "TypeScript in 5 minutes withparcel", etc.). If we state our goals of the handbook in the introduction, we may also state non-goals (like introduction to specific tooling) and could navigate people who are interested in this topic to a different ressource.I'd also introcude people to the general design vision of TypeScript here, so I can refer to them in later section. E.g. things which are currently listed at the end of the "Basic" chapter like "Type annotations never change the runtime behavior of your program."
Define common terms
Similar to how the introduction should define the term TypeScript I'd also explictly try to define certain terms which may are unknown, but used a lot. A good example is ECMAScript. The first time its used its just called "the ECMAScript specification" with a link to the spec, but not a concrete explanation. Later it's used in "Type annotations aren't part of JavaScript (or ECMAScript to be pedantic)" - maybe it would be good to explicitly explain when what term is used beforehand. The next oocurence is this:
I'd try to simplify this a little bit and be more straightforward. Something like this:
The language JavaScript as we commonly call it has a formal specification which is called ECMAScript. You can find the complete specification here. Most of the times both terms are interchangeable and thoughout this guide we'll use JavaScript, with one exception: As the language evolves and new features are added also new versions of the ECMAScript specification are created. These versions original used a major version number )like ECMAScript 3 or ECMAScript 5) and later switched to a version scheme using the current year (like ECMAScript 2015). In general we abbreviate these versions as ES3, ES2015 and so on.
But mabye this can be even dropped in the "Basics" chapter completely, when we move
tscand the downleveling section to a later chapter.Avoid noise and use a neutral tone
Things like:
A friendly casual tone is nice, but some filler make it harder to read the documentation. Some of these examples could be dropped completely (imho) and others can be rewritten like the last one.
Be as opinionated as possible
In some cases that is already done quite well ("it's best not to add annotations when the type system would end up inferring the same type anyway"), but maybe it can be taken even further.
E.g. if we would embed playground examples and would not introduce
tscso early, we could also build every example in a way that they use--strictby default. In that case I wouldn't even explain that there is a hidden--strictsetting in the background, but I'd write the complete handbook using this best practice and I'd just in a later advanced chapter tell the reader, that there are actually looser and more dangerous configurations possible.That makes reading the introduction leaner (less explanation about configurations) and you automatically teach good practices.
Avoid uncertainties
For that I think I just found one example:
What's very little and looks identical in that case? I stumbled over this question and couldn't read further, because I first had to answer it in my head. Was there something transformed I couldn't see/find or are they identical (even though just for this particular example)?
A different approach how to explain a type checker
Currently the type checker is explained like this:
Maybe we can find a more straightforward explanation which doesn't touch tranforming files in the middle of the explanation. That would probably be easier with embedded playgrounds as well.
I hope the feedback is valuable and doesn't sound too negative. Thank you very much for trying to improve the documentation. Feel free to close the issue immediately 🙃