[Content]: Typescript info is kind of buried

[JasonHassold]

📚 Subject area/topic

Typescript

📋 Page(s) affected (or suggested, for new content)

https://docs.solidjs.com/configuration/typescript

all individual reference pages for the specific tools/concepts listed in the Typescript page

📋 Description of content that is out-of-date or incorrect

The Typescript page which explains a lot of the "gotchas" to correctly setup typescript is not easily discoverable. It is currently the very last page in the learn section.

When running into a Typescript issue I think it is far more likely that people will go looking for the docs on that particular concept (for example on:*) and except the info to be under it rather than knowing to look under the Typescript page.

Especially while we don't have search nor the TS/JS toggler, I think a good stopgap would be to link from each concepts reference section to the corresponding Typescript page section so they are more discoverable.

Alternatively we could just move the individual concept sections in the Typescript page to their corresponding reference pages and just leave the Typescript page for the very general Typescript info.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

[atilafassina]

I'll be the first to agree TypeScript needs more highlight in the docs. Specially with Solid being full of little gotchas that can plague beginners.

There are 3 cases for TypeScript

1. Code snippets: that will be address by a proper Expressive-Code tab soon.
2. Explaining the foundational types and best practices for each API.
3. Highlighting gotchas that aren't particularly intuitive.

On discussing with @LadyBluenotes , our first hunch is that we should use TypeScript sparingly in the /learn section, while /references could have blocks of text and TS-dedicated explanation where appropriate. As long as there's a clear distinction to the reader where they're leaving "js-land" and entering a typed system.

We also discussed to potentially have a dedicated TS tooltip on callouts or expand the text blocks with TS-specific sections when the reader selects TS as a language. For that, we'd need a <TSBlock> that is context-aware and wrap its children in a <Show />. I wouldn't take this as a blocker to bulking up the content though. So perhaps we could have a TSBlock that just returns the regular <p> for now - for future-compatibility.

What do you think of that?

[JasonHassold]

For the 1,2,3 list I totally agree.

Also agree TS should primarily live in references.

TS specific callout blocks and expressive-code tabs for code blocks sound good, my primary concern is just having the docs be bad while we are waiting to implement these. That is why I think either of the options I mentioned are a good temporary solution.

I feel like having a Typescript section on each reference page rather than one Typescript page, or linking out from the reference pages are fairly simple changes that would improve the situation until the better solutions you mentioned are actually implemented.

I don't have any objections to the long-term plan, I just would like to solve the issue more immediately with something simple that is a step in the right direction rather than doing nothing until the full solution is ready. Pretty sure adding the links or moving those sections would take like 30 mins max and I'm happy to do it.

[LadyBluenotes]

For the 1,2,3 list I totally agree.

Also agree TS should primarily live in references.

TS specific callout blocks and expressive-code tabs for code blocks sound good, my primary concern is just having the docs be bad while we are waiting to implement these. That is why I think either of the options I mentioned are a good temporary solution.

I feel like having a Typescript section on each reference page rather than one Typescript page, or linking out from the reference pages are fairly simple changes that would improve the situation until the better solutions you mentioned are actually implemented.

I don't have any objections to the long-term plan, I just would like to solve the issue more immediately with something simple that is a step in the right direction rather than doing nothing until the full solution is ready. Pretty sure adding the links or moving those sections would take like 30 mins max and I'm happy to do it.

I'm curious what you mean by the docs being bad?

[JasonHassold]

Well with the typescript info being kind of hard to find, in an unexpected place (not paired up with the concepts), and there being no search to make it easier to find things like this that are in separate places. It seems to me like the current state of it is not good from a standpoint of discoverability.

I found it difficult to find 2 things in the last week alone and I'm probably more familiar with the docs than the average user.

Since there are plans to add all of the typescript features and content @atilafassina mentioned, it sounds like everyone agrees that the current docs is not presenting typescript info in intuitive/convenient places.