Typescript Support doc

[jennifer-shehane]

Create a doc solely for 'TypeScript support' within the 'Guides' section. We may consider having a separate section from 'Guides' called something like 'Tooling' which could include this document, Reporters, & Plugins.

If anyone wants to just write a basic markdown file of the documentation in a gist or PR, we can clean it up + add the link to the main docs after we have just the basic content.

[brian-mann]

@jennifer-shehane I noticed that this had a PR merged but this issue was never closed... I don't know why not.

Anyway here is my feedback for this page: https://docs.cypress.io/guides/tooling/typescript-support.html#

I find this document very confusing for multiple reasons:

1. There is not a clear summary of what intellisense adds. I feel like this needs to list up front the benefits such as assertion autocompletion, amongst other features. That is one of the coolest things it can do, and we aren't even promoting it.
2. The very first section suggests to add a directive. Then immediately below it, it suggests a tsconfig.json modification instead. It's not clear which one we are suggesting. It's also not clear what one does instead of another. It seems like editing tsconfig.json would make all files instantly work, without needing a directive. If this is the case, then obviously this should go first. The "one off" directive should be at the bottom as like a: "oh and you can do it as a 1-off this way, or if something isn't working in tsconfig.json.
3. The animated gif is incredibly confusing. It starts strange... with the cursor not going in the direction I would think it should go - and its missing the actual mouse pointer! Tooltips start flying in everywhere and I have no idea why it's doing this or even what this is communicating to me. The animated gif should be at the top - along with a better summary of what our typescript intellisense provides. We should show an actual autocomplete assertion, as this is one of the biggest and best reasons to use it.
4. Why is this issue still open? Can type definitions be more automatic for beginners? cypress#1236 Have we fixed this? Does this document suffice? Are there other changes we need to make in Cypress core? If we're going to work to fix an issue, let's actually tie up all the knots surrounding it.
5. We mention Typescript in two places now - Guides - and in Plugins here: https://docs.cypress.io/plugins I feel that we should point Plugins to this guide, and then inside of this Guide link to the source code. As it stands, its fractured and makes no sense.
6. I'm not sure this should be called "Typescript Support", maybe just "Typescript". You could argue that virtually every guide could be suffixed with Support. Reporter Support. Plugin Support.
7. When searching for "Typescript" I now get recipes + this guide. I noticed that we don't ever actually explain how to get typescript installed and working in cypress code. Notice how the picture below never has that section? As a user, that's why I'd be searching for Typescript. Sure, this guide points to the examples, but this guide should clearly state how you need to install Typescript in Cypress to get this behavior working. Also, now the recipes need updating to reference back to the Typescript Guide, else you'd miss the parts about configuring tsconfig.json. When you're writing new guides, you need effectively assess everywhere that this thing touches. For instance, other guides may make mention of parts of this guide. Those other guides should have their references updated to point to this new guide. In other words, every doc needs to be synchronized else it creates a fracturing state, where the user is continuously searching and bouncing around trying to find what they need - picking up little bits here and there. Here's an example of two of my latest commits (6090f5e) and (e6f5118). I added the "Best Practices" video, but then subsequently modified 5 different areas of the docs to "synchronize" them to these changes. Unless content is sprinkled around, its not effective. We have a ton of content already, and the priority should be weighted towards usability and not just adding "one more doc".

[jennifer-shehane]

Yeah, I suppose I didn't really feel like this document was complete yet, but in a good enough state that it would be helpful to our users.

1. I can add the specifics of intellisense gains.
2. So, we're not technically suggesting one way or the other, because it's dependent on your codebase. The slash directives are best for getting Intellisense if you are writing your tests in JavaScript .js files. A .tsconfig is overkill and the user may not even be completely comfortable with TypeScript enough to want to touch a .tsconfig file (aka, this is ME and how I work, slowly considering typescript, but wanting intellisense for now). The .tsconfig is what user's writing their tests in TypeScript .ts files should use.
3. The gif was quickly taken from one of gleb's tweets. I can rerecord it. My gif recorder captures mouse pointer also. 👍
4. Well, from what I have read, other libraries sound more 'plug and play' (see Vue.js for example). They have some configuration that they recommend, but it's more - let's start with TypeScript - no installs, etc. We also scaffold out our example files as .js files, and they are working on a scaffolding that would use .ts example files. But, also - I am so not an expert on how this workflow should go.
5. Honestly, I'm confused by the plugin. Do people have to have the plugin for TypeScript compilation to work??
6. I liked Vue's naming. This is debatable and I don't really care.
7. I can update the example pages to point back to TypeScript support doc. I don't feel like it is of our concern to detail to the user how to install and use TypeScript, but I can update the doc to refer to the official TypeScript doc for installation instructions.