このドキュメントでは、演習とトラックのさまざまなファイルが学習者にどのように表示されるかを、学習者がCLIとエディターのどちらを使っているかを踏まえて説明します。
ドキュメント
演習でどのドキュメントが表示されるかを決めるドキュメントには、3つの種類があります。
演習固有のファイル
これらのファイルは演習ごとに固有のものです：
-
.docs/introduction.md：その演習が学習者に教える概念を紹介します（必須）
-
.docs/introduction.append.md：既存のイントロダクションのあとに追加するイントロダクションのテキストです（コンセプト演習では使われず、プラクティス演習では任意）
-
.docs/instructions.md：演習の指示を提供します（必須）
-
.docs/instructions.append.md：既存の指示のあとに追加するテキストです（コンセプト演習では使われず、プラクティス演習では任意）
-
.docs/hints.md：演習で行き詰まった学習者が自力で抜け出せるようにするヒントを提供します（コンセプト演習では必須、プラクティス演習では任意）
-
.meta/config.json：演習の出典情報を含みます（任意）
詳しくは、コンセプト演習のドキュメントとプラクティス演習のドキュメントを参照してください。
トラック固有のファイル
これらのファイルはすべての演習で共有されます：
-
debug.md：ブラウザーでコードを書いている学習者がどのように「デバッグ」できるかを説明します（任意）
-
help.md：ヘルプの求め方についてのトラック固有の指示を含みます（必須）
-
representations.md：解答からその表現を作り出すためにどのような正規化が適用されるかを説明します（任意）
-
tests.md：テストの実行方法についてのトラック固有の指示を含みます（必須）
詳しくは、共有ファイルのドキュメントを参照してください。
Exercism全体のドキュメント
ここまでに挙げたトラックや演習に固有のドキュメントファイルのほかに、Exercism全体で共通の（つまりすべてのトラックで共有される）ドキュメントが2つあります：
- CLIを使って演習を提出する方法の説明
- ヘルプの求め方の説明
エディター
ブラウザーで演習に取り組んでいるときは、ドキュメントのファイルが適切なタイミングで表示されます。たとえば、ヒントは学習者が表示を求めない限り表示されません。また、エディターではCLIの説明を表示する必要がありません。
CLI
CLIを使ってローカルで作業する場合、ドキュメントを条件付きで表示するという選択肢はありません。そのため、CLIは関連するドキュメントを常にすべてダウンロードする必要があります。学習者がいくつものファイルを開かなくて済むように、CLIは関連するドキュメントをすべて3つのドキュメントに結合します：
README.md
このファイルには、演習の指示、イントロダクション（任意）、出典情報（任意）が含まれます。
# [exercise name]
Welcome to [exercise name] on Exercism's [track name] Track.
If you need help running the tests or submitting your code, check out `HELP.md`.
If you get stuck on the exercise, check out `HINTS.md`, but try and solve it without using those first :)
## Introduction (optional)
[Exercise-specific file: .docs/introduction.md] (optional)
[Exercise-specific file: .docs/introduction.append.md] (optional)
## Instructions
[Exercise-specific file: .docs/instructions.md]
[Exercise-specific file: .docs/instructions.append.md] (optional)
## Source
### Created by
- @[author-1 handle]
- @[author-2 handle]
...
### Contributed to by (optional)
- @[contributor-1 handle]
- @[contributor-2 handle]
...
### Based on
[source] - [source url]
HELP.md
このファイルには、テストの実行方法と、トラック全体およびExercism全体のヘルプの指示が書かれています。
# Help
## Running the tests
[Track-specific file: exercises/shared/.docs/tests.md]
## Submitting your solution
[Exercism-wide documentation: instructions on how to submit a solution]
## Need to get help?
[Exercism-wide documentation: instructions on how to get help]
[Track-specific file: exercises/shared/.docs/help.md]
HINTS.md
このファイルには、演習固有のヒントが含まれます（任意）
# Hints
## General
- Consider extracting the logic to a helper function.
