Typescript: TypeScript Webサイトとドキュメントの何が気に入らないのですか？

「ユーティリティタイプ」ページが最新ではありません

新しいユーティリティタイプは、見落とされたり、ハンドブックの[ユーティリティタイプ]ページに追加されなかったりすることがよくあります（例： Parameters<T> ）。 私はしばしばハンドブックの代わりにlib.es5.d.tsを閲覧することに頼らなければなりません。

タグ： docs

公式のTypeScriptPlaygroundは、オープンソースの代替手段ほど良くありません

https://typescript-play.js.orgは、公式のものよりも優れています。TypeScriptの複数のバージョンをカバーし、より大きなテキストを共有でき、すべてのコンパイラフラグをサポートし、デフォルトでstrictモードがオンになっています。

タグ： playground

リリースノートのインデックスページの欠如

このURL ： https://www.typescriptlang.org/docs/handbook/release-notes下に、過去のすべてのリリースノートを一覧表示するインデックスページがあればいいのにと思い

タグ： docs 、 release notes

タイプ名の用語集はありません

const a: "foo" | "bar"ようなコードを渡した場合、これを共用体型と呼ぶことを知らないかもしれません。

これはかなり低いバーですが、存在/条件付き/マップされた/などのタイプについて話し始めると、それを定義しようとするだけのページに移動できるのは良いことですが、詳細に文書化しないので、概要を知ることができますこの言語のすべての分類法の

タグ： types 、 handbook

技術者以外の人と共有するページはありません

これは、最初にエンジニアリング以外の人々（PM、非技術マネージャーなど）にTypeScriptを使用することの価値を説得するために必要でした。 結局私はこれを自分で書いたが、公式を好む

タグ： guides

明確に型指定されたドキュメントはTypeScriptドキュメントの外部にあり、古くなっています

TypeScriptプロジェクトは、これに関するドキュメントを所有している必要があります。 DefinitelyTypedのドキュメントは次の場所にあります。

• https://definitelytyped.org
• https://github.com/DefinitelyTyped/DefinitelyTyped#how -can-i-contribute

TSドキュメントには、それが何であるか、なぜ使用されるのかについての概要が含まれている可能性があり、公式サイトを廃止することができます

タグ： definitely-typed

TSを徐々に教えない

（読みやすくするために編集）ドキュメントは、意図された明確な「ペルソナ」を持っている場合に最も効果的だと思います。 これらのドキュメントが作成されたとき、ES6はまだ問題ではありませんでした。 これらのドキュメントが作成されたとき、午後にすべてのTSを学ぶことができました。

時が変わった。

私はreact-typescript-cheatsheetbcを作成しました。TSドキュメントは、es6をすでに知っていて、高度なTSを一度に学びたくない人には特に役立たないと感じました。 そのため、TSを初めて試す経験豊​​富なJS開発者を具体的にターゲットにしています。 私たちがたくさんいます。 現在のドキュメントは、「クラスとは何か」または「タイプ演算子のドキュメントと同じページにある恐ろしいジェネリックの束」のいずれかです。

特にここに、進歩的な教師として役立つ可能性のある考慮すべきペルソナの非網羅的なリストがあります。

• JSDocでTSを使いたいだけの人、ビルドステップなし
• ジェネリックをできるだけ書かずにTSを使いたい人
• コードベースをJS / FlowからTSに移行している人
• TSを初めて使用し、TSを採用したが、なじみのない詳細なエラーを初めて目にし、それに対処する方法がわからない（これは「トラブルシューティング」オーディエンスです）、またはオプトアウトする人
• TSライブラリとTSアプリを公開したい人
• 型演算子の使い方を学びたい人
• 彼らを助けるかもしれないタイプユーティリティについて学びたい人
• 型指定されていないライブラリを入力する必要がある人（.d.tsの記述を途方もなく簡単にし、可能な限り十分に文書化することは、ネットワーク効果であり、TSの関心事です）
• そして最後に、独自のジェネリック型ロジックの書き方を学びたい人たちです。
• （たぶん）TSASTをトラバースする必要のあるプラグインを書きたい人

これらはすべてTSの採用の過程の段階です。それを計画し、何をすべきかわからないために人々が脱落するドキュメントに崖がないことを確認する必要があります。

ドキュメントは、次のような神話を払拭するのに役立つと思います。

• 常に最大の型安全性が必要です（tsconfigだけでなく、入力関数で行う選択でも）
• TSはオブジェクト指向プログラマー向けです（はい、私はこれを見ました）
• TSは、JSにアクセスしてタイプを見逃すC＃/ Java開発者専用であり、JS開発者にとって実際の価値はありません。
• TSエラーを自分で解決する方法を理解できるはずです
• 一般に、そのTSには開始するための高い学習曲線があります

リソースが利用可能な場合は、特定の大規模な開発コミュニティをターゲットにして、その採用を支援することができます。たとえば、Reactだけでなく、VueやNodeなどもターゲットにできます。 これはメインドキュメントから行うことができます。たとえば、Vueドキュメントでは、コンテキスト内の実際の例に焦点を当てて、クックブックとガイドを

これはおそらく、私が想像できるように、後期段階のTS採用（つまり、TSで販売するためにより多くのドキュメント/ツール/保証/手持ちを必要とする人々）にとって大きなハードルです。

タグ： docs

リンクされたTypeScript言語仕様は完全に時代遅れです

メインページで直接、「TypeScript言語仕様」にリンクしています。

GitHubで仕様を読むか、docxまたはpdfとしてダウンロードしてください。

ただし、その仕様は完全に古く（バージョン1.8でスタック、最後の実際の更新は2016年1月）、維持されていません。 仕様についての言及はすべて削除するのが最善です。

タグ： spec specification outdated

コードサンプル用の遊び場のようなウィジェット

便利なツールチップやハイライトなどをすべて備えた、遊び場のようなウィジェットのドキュメントにあるすべてのコードサンプルを提示します。

理想的には、完全な遊び場に飛び出して、放出されたJS /タイピングを編集および確認する機能を備えています。

これは当然、公式のTypeScript Playgroundに依存しますほど良くはありません。

リリースノートにのみ存在するAPIドキュメント

unknownなどの一部のタイプは、リリースノートにのみ記載さ

タグ： docs

Fourslashの遊び場

/ tests / Cases / compilerには非常に多くのファイルがあり、ベースラインとともに、不可解な暗黒物質のように動作します。 これらのメガバイトは、docs / demosとして再利用できます。

• 次のような方法でTSプレイグラウンドにTSリポジトリから任意のファイルをロードさせます： https ：
• TS遊び場に「フォースラッシュ」を理解させる
• それらのファイルに説明的なコメントを追加する

それは、誰かが興味深い構文のケースにURLリンクすることを可能にし、人々が他のファンキーなテストをいじくり回して提出するのを助けます。

与えられたTS構文を説明する遊び場

理解するのが本当に難しい複雑なTS構文に出くわすことは難しくありません。 ユニオンとファンキーなインデックス付きタイプを介して組み合わされた再帰ジェネリック...このような恐ろしいムカデの大きな巣の1つは、たとえばタイピングです。

角度が豊富な構文のチャンクを貼り付けて、人間が消化できる詳細なビューまたは図を観察できたとしたらどうでしょうか。 Aがクラスであり、 Bが共用体型であり、 CがDジェネリックパラメーターであることは間違いありません。等々。

素朴な「verboseASTpretty-print」から始めて、これは時間とコミュニティの貢献とともに、より深いパターン認識と、より豊かなインタラクティブなビジュアルとUMLのような図の両方に拡大することができます。

ドキュメントの検索はありません

ReactドキュメントのようにDocSearchを使用するなど、信頼できる唯一の情報源としてメインドキュメントを使用するのではなく、typescriptを使用して何かを行う方法をグーグルで検索する必要があることがよくあります。

タグ： search 、 exploration

コミュニティプロジェクトを強調する

これは、交流会、コミュニティトーク、本などです。

しかし、誰かが学ぶことができるTypeScriptを使用するより大きなソフトウェアプロジェクトも可能です。

タグ： Community

特定のコンパイラフラグをオンにするためのガイドを提供する

たとえば、 noImplicitReturnsをオンにした場合、どのような問題が発生し、どのように処理すればよいですか？ これらの種類の推奨事項は、これらのフラグが導入されたときのバージョンリリースノートとともに出荷されるため、検索するのは難しいです。

タグ： tsconfig

コンパイラエラーインデックスページを作成する

rust言語はこれを開始するのにかなりの労力を要します（TSには最近1,000を超えるエラーがあります）が、tscのエラーメッセージングは​​簡潔であり、サイトにそれらを置くと、検索エンジンでインデックスを作成でき、改善可能で、サンプルコードを使用できます。

タグ： compiler

角度が豊富な構文のチャンクを貼り付けて、人間が消化できる詳細なビューまたは図を観察できたとしたらどうでしょうか。

これはすばらしいと思いますが、場合によっては、型がどのように分解されるかについての高度に構造化された説明（自動生成はある程度可能に聞こえます）は、型とパターンの一般的な組み合わせを認識するほど有用ではないと思います。特定の目標。 例として、これが何であるかを誰かに説明してもらいたいとしましょう。

type X<T extends object> = {
    [K in keyof T]: T[K]
}[keyof T]

私はあなたにそれを言うことができます

Xは、 object制約されている1つの型パラメーターTを持つ型エイリアスです。 Tでインスタンス化されると、マップされたタイプが生成されます。ここで、タイプkeyof T各構成要素Kについて、値はインデックス付きアクセスタイプT[K] 。 次に、 Xは、タイプkeyof T 、そのマップされたタイプにインデックス付きアクセスタイプを生成します。

しかし、TypeScriptの実用的な知識を持った人間以外の人が作成することは、はるかに役立ちますが、非常に困難です。

Xは、 Tのメンバー値のタイプの和集合を取得します。

このようなパターンの「レシピ」を集めておくと便利かもしれません。

Advanced Typesページは、非自明な型の一種のゴミ捨て場です（ PHP静的分析ツールに関するTypeScriptのアイデアをたくさん盗んだので、そのページにたくさん出くわしました）。

そこにあるたくさんのアイデアは相互に関連していますが、それはページ間のハイパーリンクでかなり行うことができます。

Type Guard / Type Predicateセクションは、特に独自のページに値するように感じます。

タイプスクリプトライブラリを作成するためのガイダンス

Typescriptで書かれたライブラリを出荷するのはとても簡単ではないことがわかりました。 ターゲットの消費者に応じて考慮すべき多くのエッジケース。 私はこれについて完全に議論の余地がある私自身の意見を持っていますが、図書館の著者のための公式ガイダンスを文書化することは素晴らしいでしょう。

タグ： libraries 、 guidance

モバイルナビゲーションは難しい場合があります

携帯からウェブサイトのハンドブックが読めないのが残念です。 また、ハンドブックの各ページのページの下部に前/次のナビゲーションがあると便利です。

ツイートから

タグ： nav

より現実的な例を使用する

現在の例のいくつかは、文字ベースの命名規則（A、B、C）または関連性のない用語（foo、bar、baz、args、objなど）を使用して、過度に一般的または抽象的です。 より多くの実際の例（形状、動物、製品、ユーザー）と正当なユースケース（API呼び出し、ロギング、エラー処理、データフォーマット）を見たいと思っています。 これは、ジェネリックスやアドバンストタイプなど、すでに抽象化されている概念に特に役立ちます。

注：ドキュメントの一部の領域ではすでにこの問題が処理されています👌🏻ですが、ヒットとミスがあります。

タグ： examples

ライブラリとベストプラクティスの例

さまざまな種類の関数を入力する方法を示します。 lodashのように、ピック、エクステンド、フラット化など、あらゆる種類の凝った機能があります。それらの入力方法を説明してください。

徐々に複雑さを増していくライブラリ。 TSの特定のものが本番環境でどのように使用されているかを示すコミットへのリンクをさらに読むこともできます。

最終的に構築されるものが何であれ、誰かが例を追加するのが非常に簡単であることを願っています。 gitrepoのようなTSハンドブックになると思います。

最高のオープンソースプロジェクトは通常、最高のドキュメントと新しいユーザーエクスペリエンスを備えています。

TSを新しいユーザーにとってさらに歓迎するようにしましょう。

tsconfigオプションのより良い説明

[コンパイラオプション]ページの現在の説明

• 各オプションの非常にあいまいな説明と、それがコンパイルと型チェックにどのように影響するかを示します。 いくつかの例は本当に役立つかもしれません。
• 表形式では、説明に少しスペースがあります
• TypeScriptバージョンに関する情報はありません
• アルファベット順は役に立ちません。 target 、 module 、 libのように、いくつかのオプションは互いに密接に関連しています。 それらを別々に見ると、それらをよく理解するのは難しいです。 最初にtargetを理解しないと、 libオプションを理解できません。
• ほとんどの場合、人々はtsconfgファイルでこれらのオプションをtscオプションとしてではなく使用するため、現在の形式は初心者にとって混乱を招く可能性があります。
• いくつかのオプションのより詳細な説明はドキュメント全体に散らばっています。たとえば、 @types 、 typeRoots 、 typesオプションはtsconfig.jsonページで説明されており、 baseUrlとpathsモジュール解像度のpaths

これは、特定のコンパイラフラグの提案

編集：
複合プロジェクトの構築に関連するオプションのような新しいオプションは言うまでもありません。ドキュメントには情報がなく、リリースノートとGitHubの問題に基づいて全体像をまとめることを余儀なくされています。

タグ： tsconfig

ドキュメント、ブログ、その他の公式リソースを1か所に集めます

TypeScriptに関するすべての公式リソース（例： www.typescriptlang.org ）を1か所に集めることができれば素晴らしいでしょう！ 😊

たとえば、v3.5の発表に関するブログ投稿は別の場所（ devblogs.microsoft.com ）にあります。
https://devblogs.microsoft.com/typescript/announcing-typescript-3-5/

そして、v3.4リリースノートは別の場所にあります：
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html

これはTypeScript開発者にとってあまり役に立たず、混乱を招くものではないと思います。 😕

タグ： blog 、 resources

UIフォームに設定とプロジェクト設定を入力してtsconfig.jsonを作成します

ドキュメントに、ターゲット環境（ブラウザー、nodeJS）、ユーザー設定（ユ​​ーザーが望むように厳密または寛大）、およびプロジェクトディレクトリ構造に適したtsconfig.jsonの生成に役立つフォーム/ウィザードが含まれていると便利です。 現在、 TSコンパイラオプションにはいくつかの非推奨オプションといくつかのコンパイラフラグが含まれており、一見するとほとんど同じことをするように見えます（たとえば、パス/ディレクトリ/ルートに関連するいくつかのオプションの違いは何ですか）。 生成されたtsconfigは、MicrosoftTypeScriptコアチームのベストプラクティスに準拠している必要があります。 その他のガイドとなる質問には、次のものがあります。

• TypeScriptを使用したプロジェクト開発チームの経験は何ですか（「TSの達人」のすべての厳密なオプションを提案しながら、「JSからTSへの移行パス」に関連するコンパイラオプションを初心者に提案する可能性があります）
• はライブラリまたはアプリケーションのプロジェクトです（依存関係がほとんどないライブラリの場合、 strictNullChecksなどのいくつかの厳密な機能を使用する方が簡単な場合があるため、ユーザーエクスペリエンスによっては推奨される場合があります）
• JSX / TSX（React）を使用したアプリケーションです
• デコレータを使用するフレームワーク/ライブラリを使用していますか
  
  
  
  • デコレータメタデータが発行される必要があるため、実行時にフレームワーク/ライブラリで使用できます（例としてAngular、Aureliaなどのフレームワークとライブラリに言及します）
  
  

タグ： tsconfig 、 examples 、 guides 、 wizard 、 exploration

@ortaモバイル版の遊び場を作るか、少なくとも現在のものを適応させるのは素晴らしいことだと思います。 今のところ、遊び場はモバイルではひどいように見えます（スクリーンショットはiPhone7で作成されています）。

ウェブサイトの「ハンドブック」エリアに、オブジェクトリテラルとそれらを入力するさまざまな方法について具体的に説明したセクションがあればいいのにと思います。

たとえば、「任意のプロパティを持つtypescriptオブジェクトリテラル」や「1つの必須プロパティとその他のプロパティを持つtypescriptオブジェクトリテラル」のようなものを常にGoogleで検索する必要があります。

そして、私は常に{ [key: string]: any }タイプを検索する必要がありますが、これは実際にはどこでも議論されていません。

このようなもののいくつかは「インターフェース」で話されていますが、それはすぐには明らかではありません。

ベンダータイプの拡張

DefinitelyTypedタイプまたは他のベンダーモジュール定義を操作するときに、定義を次のいずれかに微調整する必要があることに気付くことがあります。

1）既存の定義を上書き/変更する
2）新しいメソッド/プロパティを追加します

さまざまなシナリオでタスクを実行するための適切な方法に関するドキュメントを見つけることができませんでした。 自分でやる必要があるときも、良いメモをとっていません🐙。 https://www.typescriptlang.org/docs/handbook/declaration-merging.htmlは、ファーストパーティコードの問題に取り組んでいますが、サードパーティのモジュールタイプ/エクスポートに対してそのアドバイスが機能するようにはしていません。

明らかに、PRをすぐに開いて、対応するリポジトリのタイプを修正/更新するのは素晴らしいことですが、マスターブランチにマージされるまでに時間がかかることがあり、ワークフローが中断され、一時的なany変換とフォローアップTODO。

タグ： vendor

コンパイラAPIドキュメント

wikiには、コンパイラAPI（https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API）の使用に関する情報がいくつかありますが、特定の目標を達成するためにそれを使用する方法の例のみを示しています。 存在する特定のオブジェクトとメソッドをリストし、それらが何をするのかを学ぶために、より多くのJSDocスタイル情報があれば素晴らしいと思います。 今、私はAPIを学ぼうとしていますが、何が起こっているのかを理解するためにtypescriptソースを調べる必要があります。

（wikiに記載されているようにAPIがまだ安定していないという理由だけでこれが行われていない場合は、無視してください）

タグ： compiler

既存の言語と比較してTSに焦点を当てたチュートリアル

多くの人が2番目（またはそれ以上）の言語としてTypeScriptを利用しています。 TypeScriptの学習を簡素化する1つの方法は、TypeScriptを既に知っている既存の言語と比較することです。 JS、Java、C＃、PHP、C（+ CPP）、Rubyなど、人気のある上位のプログラミング言語を取り上げることができます。次に、その言語がどのように機能するかについての知識があることを前提としたチュートリアルを指示しました。

今のところ、私たちはあなたがJSを知っているという仮定だけをしています。

タグ： tutorials

デフォルトでアクセス可能であることを確認します

Accessibilityinsights.ioのようなリンターが合格することを確認します

タグ： infra

遊び場の短くて共有可能なURL

TypeScriptプレイグラウンドの「共有」ボタンがソースコード全体をURLにダンプするのではなく、短いURLを生成するのは素晴らしいことです。

または、遊び場に配置するgithubの要点IDをURLに含めることを許可します。 例： https://www.typescriptlang.org/play?gist=eb25a1f350e50d6ed3561a777fbfe424

タグ： playground

さまざまな設定の例（さまざまなユースケース/シナリオ用）

TSコードベースを構成する方法と、さまざまなコードベースに対してどのような例に従うことができるかを知るのは難しいと感じたので、 https：//github.com/microsoft/TypeScriptSamples/のような例のリストがWebサイトに掲載されると便利です。 tsconfig.jsonを構成する方法と、意図したとおりに機能するようにTSファイルを構造化する方法を示します。

タグ： docs 、 examples

ドキュメントがウィキとハンドブックに含まれる明確な理由はありません

ウィキのthisの

トピックとタイトル間のナビゲーションを改善する

ハンドブック§高度なタイプのような巨大なトピックは、別々のタイトル間のナビゲーションが貧弱で、上へのボタンもありません。 フローティングナビゲーションメニューを追加すると本当にいいでしょう。 現在、あるタイトルから別のタイトルにジャンプしたり、必要なタイトルをすばやく見つけたりすることは困難です。

これは、このAssembly Scriptgitブックに記載されているナビゲーションの良い例です。https ：

タグ： website 、 handbook 、 navigation

モバイルフレンドリーな遊び場コード編集

私が理解しているように、構文の強調表示や他のすべてのIDE機能を使用したモバイルフレンドリーなコード編集は面倒です。

しかし、私は自分の携帯電話で、デスクトップ/ラップトップから離れて、コードスニペットで遊んでみたいと思うことがよくあります。

モバイル用のシンタックスハイライトされたエディターの代わりに、プレーンな<textarea>フィールドを気にしません。

エラーは、別のページ、ポップアップ、またはその他のhtml要素にある可能性があります。

タグ：遊び場、モバイル、コードエディター

ブラウザ互換のes6モジュール用の.js拡張機能を追加するドキュメント

TypeScriptを完全に使用して、インポートの名前に.js拡張子を追加するだけで、ブラウザーで機能するes6モジュールを生成できることについてはどこにも言及されていません。 この情報が存在すると思われる唯一の場所は、このスレッドです。
https://github.com/Microsoft/TypeScript/issues/16577#issuecomment -343610106

TSのどのバージョンがそれを追加したかはわかりませんが、「。/file.js」などのインポートが機能するようになりました（ファイルが実際にfile.tsであっても）。

私にとってこれは大規模な機能でした...しかし、公式には存在しませんか？！

Advanced Typesページには、 Omit<T, K>タイプは含まれていません。

Omit<T, K>は最近TypeScript 3.5でAdvancedTypes]ページにはまだ次の免責事項があります。

注：Excludeタイプは、ここで提案されているDiffタイプの適切な実装です。 差分を定義する既存のコードを壊さないように、Excludeという名前を使用しました。さらに、この名前は型のセマンティクスをよりよく伝えていると感じています。 省略は含まれていません簡単にPickと書かれているのでタイプします>。

Lintersのプロジェクトセットアップドキュメントを提供する

プロジェクトのセットアップの一部として、Linterを使用してセットアップする方法を含めます。ほとんどの場合、プロジェクトがそれ自体を使用することになっているtypescript-eslintだけです。

タグ： linter

最も一般的にヒットするエラーやTypeScriptの制限をカバーするものは何もありません。

TypeScriptを初めて学習するときは、TypeScriptでサポートされない+サポートされない特定のパターンがあります。 最も単純なものの1つ：

const buildResult = (name?: string) => {
  const result = {};
  if (name) {
    result.name = name; // error, this property doesn't exist on {}
  }
  return result;
};

私はTypeScriptを会社に紹介し始めましたが、このようなケースが頻繁に発生するので、FAQ /トラブルシューティングスタイルのガイドでそれらを文書化し始めました。 それは急速に成長しています（これは大まかな状態であることに注意してください）：

一度に1つのプロパティでオブジェクトを構築します
必要なときにエラーが発生しない理由：過剰なプロパティチェック
ユニオンからなど、オプションのプロパティにアクセスする方法
Object.keysとObject.entriesがあなたが望むことをしない理由
フィルターフィルターを作成し、エラーなしで作業を削減します
タイプの改良が失われている

この情報のいずれかがドキュメントにある場合、私はそれを見つけることができませんでした。 私はこれらを何年にもわたる試行錯誤を通して理解し、Githubで最もリンクされている問題を読んでいます。

タグ： errors 、 troubleshooting 、 limitations

カスタムタイプ定義を追加する方法に関する明確なドキュメントを提供する

型を含まず、 @types/*パッケージを利用できないライブラリがいくつかあります。 プロジェクト内でこれらの独自の宣言ファイルを記述できるようにしたいのですが、それらを記述してtypescriptで認識させるための「正しい」方法に関するドキュメントがないようです。 npmからモジュールをインポートしているとしましょう。 declare module xを使用する必要がありますか？ またはdeclare module "x" ？ または名前空間を使用しますか？ または単にタイプをエクスポートしますか？ これらのファイルを配置する必要がある特定の場所はありますか？ どの構成オプションを設定する必要がありますか？ typeRoots ？ types ？ paths ？ include ？ または何？ -これまでに見つけたのは、紛らわしいエラーメッセージ、説明が不十分な構成オプション、古いSOの質問だけです。

タグ： docs

オフラインドキュメントの欠如

gitやnpmなどの最新の基本的な開発ツールには、オフラインのドキュメント/リファレンスにアクセスできる独自のコマンドのサブセットがあります。

$ git help ls-remote
$ npm help search 

そのような機能があればいいと思います（TSは少し異なりますが）。
これにより、site / githubなどを参照しなくても、 helpようなコマンドを使用してローカルでドキュメントを探索できます。

$ tsc help tsc # basic CLI arguments desc
$ tsc help config # opens up html page of the tsconfig.json docs
$ tsc help v3.5 # opens up html page changelog
$ tsc help enum # finds pages containing `enum` type and hints their names/opens them up

タグ： offline 、 search 、 cli 、 local

例には、より明確に区別できる色が必要です。

それがどうあるべきか：

const whomstve = (name: string) => name + 'is life'

現在の状況：

const whomstve = (name: string) => name + 'is life'

少し青みがありますが、それだけです。

こんにちは皆さん、私は先月、一般的なサイト構造と全体的なドキュメントについて考えながら、この問題に注目してきました。 この問題が解決したので、ドキュメントをどのように表示するかについてもう少し理解できました。

読みやすさのために少しシャッフルしながら、反応に基づいてこれらすべてのポイントを調べてみましょう。

APIドキュメントはリリースノートにのみ存在する場合があります

これは注意が必要です。これは、リリースノートに何が含まれているのかが今のところわからないためです。

言語と構文に関しては、言語全体を見直している新しいハンドブックでこれが修正され、改善されることを期待しています。 残りのドキュメントについては、新しいサイトマップの一部でほとんどのケースをカバーできると思いますが、それでもWIPです

ウェブサイトで検索しない

ええ、私は同意します、これは新しいサイトにとって間違いなく重要です。

ウェブサイトはクローズドソースです

修理済み！ https://github.com/microsoft/TypeScript-website

新しい作業はマスターブランチから外れますが、今のところ古いサイトは上からアクセスでき、PRを取得しています。 TypeScriptリポジトリからここにも問題を移動しているので、すべてを追跡する方が簡単です。

ユーティリティページが最新ではない

修理済み！ 部分的に私は多くのPRを統合し、コミュニティから最新のハンドブックを入手しました。 それがナビゲーションに表示されることを確認するだけでなく（Web検索のみからではなく）

TS構成オプションの説明の改善

私は週末にこれを調査し始めました（コンパイラとWebサイトがこれらのドキュメントの同じ初期データソースを共有することをどのように確認できますか？また、より多くのコンテキストを提供するためにWebサイトがその上に何を構築できますか）

これまでの方向性のいくつかの例：

• 2017年からの私自身のメモ
• 私はEthanArrowood @matterhorndevとチャットしてきましたが、そのtsconfig-uiはTSConfigエクスプローラーを作成するための基盤になる可能性があります

遊び場は他の選択肢ほど良くありません

修理済み！ 私はこれを、私が遊び場にしたいと思っている一般的な方向への前向きな足がかりだと考えています。 プレイグラウンドを真に最高の状態にするために、プレイグラウンドがどのように見え、どのように感じられるべきかについて、より長期的な視点を提供するモックアップの例をいくつか紹介します。

（ figmaの探索についてはクリックしてください）

遊び場の短い共有可能なURL

修正済み。以下を参照

タイプ名の用語集はありません

コンパイラーを学びながら、私は自分で

[遊び場ex1、遊び場ex2]

TSを徐々に教えない

これは、新しいハンドブックで対処し、＃29288の一部を引用することを目的としています（ New handbookまでスクロール）

TypeScriptの対象読者が広いため、すべてのユーザー向けの一般的なドキュメントを作成することは困難です。現在のハンドブックの長所（および短所）の1つは、すべてのユーザーに一度にサービスを提供しようとすることです。 TypeScriptを学ぶときにさまざまな期待を抱く開発者のグループがいくつかあり、さまざまな概念の公開レベルを調整する必要があります。 それを踏まえて、私たちの目標は、ハンドブックを3つの異なる部分に編成することです。

1. カスタマイズされた紹介（コアハンドブックのセットアップ）
   
   
   
   1. コアハンドブック（誰もがこれを読む）
   
   
   2. リファレンスページ（ディープダイブ/付録のようなもの）
   
   

事実上、いくつかの異なる出発点があり、周囲の生態系に慣れたら、言語を教えようとします。

それはコメントのすべてに対処していますか？ いいえ、ほんの始まりです。 私が持っている現在のサイトマップはかなり広範囲であり、これらは私が興味を持っているタイプの問題です

私は現在のサイトマップのクックブックとガイドにいくつかの小刻みに動く余地を残しました。クックブックは、より多くのコミュニティサポートを奨励できるものです。

ガイドを提供する

私は時間をかけて、現在TypeScriptWebサイトにある現在のコードサンプルの分類と更新を開始しました。 公式ドキュメントにリダイレクトするよりも、どちらのサンプルを残しておくほうがよいかはまだわかりません（たとえば、プロジェクトがTypeScriptをネイティブにサポートしていて、独自のドキュメントがある場合）

上記と同様に、サイトのクックブックと実際のガイドのセクションでこれをカバーするのに十分だと思います

言語仕様が古くなっています

ええ、メインリポジトリから完全に削除できるかどうかはわかりませんが、新しいサイトでは言及されません。

コードサンプルにIDEのようなエクスペリエンスを提供する

これは現在、新しいハンドブックサイトにありますが、新しいサイトにも移植する必要があります。 また、ハイライトとインラインエラーメッセージングも提供します。これは私が興奮していることです。

コンパイラエラーインデックスページ

これが発生するかどうかは定かではありません。一部、TypeScriptには多くのエラーコードがあり、それらはかなり定期的に変更されています。 完全に機能するサイトとドキュメントができたら、戻ってくる価値がありますが、今のところは後回しになっています。

実際の例をもっと見る

これまでのところ、新しいハンドブックはこれで良い仕事をしています👍🏾-私たちはそれをそのように保つことを目指すことができます。 残りのドキュメントでは、そのように見えるものをすべて変更してみます。

サイトでのモバイルサポートは弱い

新しいサイトにMicrosoftデザインシステム（fluid）を使用することを検討しています。つまり、モバイルサポート（アクセシビリティ付き）は「ほとんど無料で」提供されるはずです。

遊び場のように少しトリッキーな複雑なものがあるので、電話サイズのモバイルにはブラウジング/探索の考え方が適していると思います。 だから、私はそれが読み取り専用の経験に少し近いというモックアップを持っています：

tscヘルプの改善を探る

私はこれを受け入れていますが、typescript CLIは実際にはコンパイルという1つのコマンドにすぎません（そのため、サブコマンドに関するヘルプは必要ありません（--initはちょっとそれを壊しますが））

DTSの改善に関するアドバイスを提供する

ええ、私は間違いなくタイプされたウェブサイトをタイプスクリプトのウェブサイトにマージし、それらのドキュメントを統合することを計画しています。 それらの_すべて_がサイトに住むかどうかはまだ議論の余地があります。 明確にタイプされたリポジトリに貢献する実際の実装の詳細を保持するのにはいくつかの正当な理由がありますが、高レベルの概要はサイトに存在できます。

ドキュメント/ブログ/リリースノートを統合する

トリッキーなものですが、ブログ/リリースノートに対する答えはまったくありません。 私たちは他のすべての人と一緒にマイクロソフト製品のブログシステムを使用していますが、それらすべてをWebサイト自体に移動するのが良い考えかどうかはわかりません。 私たちはそれを時間に近づけることができます。

簡単な面として、私は間違いなくこの種の情報をwikiから削除し、Webサイト内（サイト検索でインデックスを作成できる場所）にのみ残したいと思います-TypeScriptwikiは特に貢献するために残したいと思いますTypeScriptおよびTypeScriptコンパイラAPIの操作（たとえば、 import * as ts from “typescript”を使用する場合、または言語サーバープラグインを構築する場合）

最も一般的にヒットするエラーをカバーする

これは上記に関連しています-この種の問題に関する非常に広範なFAQページがありますが、これはwikiで発見したばかりです（TSを使用してから3年）。

これをベースラインとして、回答とともにメインWebサイトに取り込み始めることができます。

構文の強調表示を追加

はい、同意します、ありがとう！

全体として、これらの多くは積極的に調査または取り組んでいると思います。ドキュメントの作業を続けているので、フィードバックをお待ちしています。

素晴らしい仕事に感謝します@orta ！

個別に作成するのではなく、PlaygroundエディターでVSCode tsconfigエクスペリエンスを借用/改善/コラボレーションするのはどうですか？

Playgroundをより良くし、VSCodeの既存のエクスペリエンスはすでに半分まともです。

どういう意味かよくわかりません。 VS CodeのオートコンプリートJSONスキーマ機能のように？ JSONエディターの部分でそれを行うことを計画していましたが、ラベル付きのGUIとしてのすべてのオプションの概要は、すべてのオプションを確認して選択するための便利な方法です。

@orta新しいハンドブックが公式ハンドブックになると、現在のハンドブックのセクションを指すURLは壊れますか？ または、新しいハンドブックは別のURLにありますか？ 過去数年間にSOの回答にハンドブックのリンクを大量に入れてきたので（他の人もこれを行ったと確信しています）、すべてが壊れた場合は残念です。 （一般的なドキュメントの移行計画について話すためのより良い問題や場所はありますか？）

@orta @jcalz同じことを不思議に思ってい

はい、私はURIを

ハンドブックに新しいURLルートを使用し（たとえば、 docs/handbook/x.htmlなく/handbook/x.html ）、古いページをのマップを介して最も近い同等のものにリダイレクトする可能性が高いと思います。ある種。

このリポジトリのすべてのgithubラベルの意味を知りたいのですが。 それらのいくつかは自明ですが、他はそうではありません。

たとえば、「提案が必要」は私にはわかりません。 すべてのラベルに、すでにあるように長い説明を付けると役立ちます。

_specific_コンパイラオプションのドキュメントにリンクできません

私のチームはTypeScriptに比較的慣れていないため、 tsconfig.jsonは頻繁に変更されます。多くの場合、特定のコンパイラオプションのドキュメントを次の形式で紹介したいと思います。

https://www.typescriptlang.org/docs/handbook/compiler-options.html#strict-null-checks
(or)
https://www.typescriptlang.org/docs/handbook/compiler-options.html#strictNullChecks

このようなリンクは機能しませんが、私はそれらを機能させたいと思います。

現在、そのページに表示される唯一のHTML IDは＃compiler-optionsです。これは、基本的に一番上にあるため、それほど便利ではありません。ただし、各オプションのIDを持っていると、ユーザーをページの目的の部分。

タグ： compiler

@ Tyler-マーフィーは今それを修正しました

@ ssalka-ええ、新しいtsconfigドキュメントにある良い呼び出しです

-

この号を締めくくります。ハンドブックと新しいサイトにさらに踏み込んだら、同じ前提で将来新しい号を再開します👍

Typescriptプレイグラウンド：
夢中になっているような気がしますが、プロジェクトを保存して共有するための単純な「共有」オプションが見つかりません（たとえば、githubの問題に追加するため）。
「エクスポート」の下にすべてのリンクが表示されますが、「共有」は表示されません。

Typescriptプレイグラウンド：
夢中になっているような気がしますが、プロジェクトを保存して共有するための単純な「共有」オプションが見つかりません（たとえば、githubの問題に追加するため）。
「エクスポート」の下にすべてのリンクが表示されますが、「共有」は表示されません。

例：プレイグラウンドリンク

新しいサイトは本当に素敵に見えます！ しかし、私はこのリクエスト（コンパイラオプションのアンカーリンク）が😕に到達しなかったことに気づきました

対応するのは本当に簡単なリクエストであり、初心者にとって非常に役立つようです。 将来のアップデートでそれを見ることを願っています！