Деякі файли документації стосуються і концептуальних вправ, і практичних вправ. Ці файли, спільні для всіх вправ, лежать у каталозі треку exercises/shared/.docs:
-
debug.md: пояснює, як учень, який програмує в браузері, усе ж може займатися «debugging» (необовʼязковий)
-
help.md: містить вказівки, специфічні для треку, про те, як отримати допомогу (обовʼязковий)
-
representations.md: пояснює, які нормалізації застосовуються до рішення, щоб створити його представлення (необовʼязковий)
-
tests.md: містить вказівки, специфічні для треку, про те, як запускати тести (обовʼязковий)
Документ Presentation описує, як ці файли використовуються для показу вмісту учневі.
Файл: debug.md
Призначення: пояснити, як учень, який програмує в браузері, усе ж може займатися «debugging»
Наявність: необовʼязковий
Редактор у браузері не має вбудованої підтримки debugging. Якщо тестовий раннер треку підтримує перехоплення виведення в консоль, учень усе ж може певною мірою займатися «debugging», і цей документ пояснює, як це робити.
Вміст цього файлу показується лише в онлайн-редакторі; CLI ігнорує цей файл.
Приклад
# Debug
To help with debugging, you can use the fact that any [console output](https://www.programiz.com/csharp-programming/basic-input-output) will be shown in the test results window. You can write to the console using:
```csharp
Console.WriteLine("Debug message");
```
Файл: help.md
Призначення: пояснити, як учень може отримати допомогу
Наявність: обовʼязковий
Опишіть, як учень може отримати допомогу саме на цьому треку (а не в межах усього Exercism).
Вміст цього файлу використовує лише CLI, який додає його до файлу HELP.md.
Вказівки мають бути короткими й по суті.
Можна посилатися на такі ресурси, як канали Gitter, форуми чи списки розсилки: будь-що, що допоможе учневі зрушити з місця.
Посилання в цьому документі можуть перетинатися з посиланнями в docs/LEARNING.md або docs/RESOURCES.md.
Цей документ не повинен посилатися на ресурси допомоги в масштабі всього Exercism (незалежні від треку), бо вони автоматично потраплять до файлу HELP.md.
Приклад
# Help
To get help if you're having trouble, you can use one of the following resources:
- [Kotlin Documentation](https://kotlinlang.org/docs/reference/)
- [Kotlin Forums](https://discuss.kotlinlang.org/)
- [Kotlin Slack Channel](https://kotlinlang.slack.com/): [get invite here](https://slack.kotlinlang.org/)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/kotlin)
- [Kotlin Subreddit](https://www.reddit.com/r/kotlin)
Файл: representations.md
Призначення: пояснює, які нормалізації застосовуються до рішення, щоб створити його представлення
Наявність: необовʼязковий
Коли трек має реалізований репрезентер, для кожного надісланого рішення буде створено представлення.
Цей документ має перелічувати всі нормалізації, які репрезентер застосовує до рішення.
Це допомагає наставнику, коли він додає коментарі до представлення.
Приклад
# Representations
The representer applies the following normalizations:
- All comments are removed
- All import declarations are removed
- The code is formatted
- Identifiers are normalized to a placeholder value
Якщо на треку є файл docs/REPRESENTER_NORMALIZATIONS.md, радимо посилатися з нормалізацій на відповідний розділ у цьому файлі.
Файл: tests.md
Призначення: містить вказівки, специфічні для треку, про те, як запускати тести
Наявність: обовʼязковий
Опишіть, як запускати тести для цієї конкретної вправи.
Вміст цього файлу використовує лише CLI, який додає його до файлу HELP.md.
Вказівки мають бути короткими й по суті.
Файл docs/TESTS.md може містити докладніший опис того, як запускати тести.
Приклад
# Tests
To run the tests, run the command `dotnet test` from within the exercise directory.
Перезаписування
Примітка: це ще не реалізовано
Вправи можуть перезаписувати файли, специфічні для треку, створивши файл з такою самою назвою в каталозі .docs вправи (наприклад, .docs/debug.md). Це має бути потрібно лише зрідка (якщо взагалі буде потрібно).
