Презентація

Цей документ описує, як різні файли вправ і треків подаються учневі, з огляду на те, чи користується учень CLI, чи редактором.

Документація

Є три типи документації, які визначають, яку документацію буде подано для вправи.

Файли конкретної вправи

Ці файли стосуються кожної окремої вправи:

  • .docs/introduction.md: знайомить учня з концепцією (концепціями), яких навчає вправа (обовʼязковий)
  • .docs/introduction.append.md: додатковий текст вступу, який дописують після наявного вступу (не використовується в концептуальних вправах, необовʼязковий для практичних вправ)
  • .docs/instructions.md: містить вказівки до вправи (обовʼязковий)
  • .docs/instructions.append.md: додатковий текст вступу, який дописують після наявних вказівок (не використовується в концептуальних вправах, необовʼязковий для практичних вправ)
  • .docs/hints.md: містить підказки для учня, які допомагають вибратися із глухого кута у вправі (обовʼязковий для концептуальних вправ, необовʼязковий для практичних вправ)
  • .meta/config.json: містить інформацію про джерело вправи (необовʼязковий)

Докладніше дивіться в документації з концептуальних вправ і практичних вправ.

Файли конкретного треку

Ці файли спільні для всіх вправ:

  • debug.md: пояснює, як учень, який пише код у браузері, все ж може займатися «debugging» (необовʼязковий)
  • help.md: містить вказівки, специфічні для треку, про те, як отримати допомогу (обовʼязковий)
  • representations.md: пояснює, які нормалізації застосовуються до рішення, щоб створити його представлення (необовʼязковий)
  • tests.md: містить вказівки, специфічні для треку, про те, як запускати тести (обовʼязковий)

Докладніше дивіться в документації про спільні файли.

Документація для всього Exercism

Крім зазначених вище файлів документації, специфічних для треку чи вправи, є два фрагменти документації, спільні для всього Exercism (а отже, для всіх треків):

  • Вказівки щодо використання CLI, щоб надіслати вправу
  • Вказівки щодо отримання допомоги

Редактор

Коли ми працюємо над вправою в браузері, файли документації показуються в належні моменти. Наприклад, підказки не показують, доки учень не попросить їх показати. Редакторові також не потрібно показувати вказівки щодо CLI.

CLI

Коли ми працюємо локально через CLI, у нас немає можливості показувати документацію вибірково. Тому CLI завжди завантажує всю відповідну документацію. Щоб учневі не доводилося відкривати кілька файлів, CLI обʼєднує всю відповідну документацію в три документи:

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.