برخی از فایلهای مستندات هم به تمرین مفهومی و هم به تمرین عملی مربوط میشوند. این فایلهای مشترک میان تمرینها در پوشهی exercises/shared/.docs مسیر قرار دارند:
-
debug.md: توضیح میدهد که دانشآموزی که در مرورگر کد مینویسد چطور میتواند همچنان «debug» کند (اختیاری)
-
help.md: شامل دستورالعملهای مخصوص این مسیر دربارهی چگونگی دریافت کمک است (الزامی)
-
representations.md: توضیح میدهد که برای ساخت بازنمایی یک راهحل، چه نرمالسازیهایی روی آن اعمال میشود (اختیاری)
-
tests.md: شامل دستورالعملهای مخصوص این مسیر دربارهی چگونگی اجرای تستها است (الزامی)
سند ارائه توضیح میدهد که این فایلها چگونه برای ارائهی محتوا به دانشآموز استفاده میشوند.
فایل: debug.md
هدف: توضیح این که دانشآموزی که در مرورگر کد مینویسد چطور میتواند همچنان «debug» کند
حضور: اختیاری
ویرایشگر داخل مرورگر هیچ پشتیبانی داخلی برای debug ندارد. اگر اجراکنندهی تست این مسیر از ثبت خروجی کنسول پشتیبانی کند، دانشآموز همچنان میتواند نوعی «debug» انجام دهد و این سند توضیح میدهد که چطور این کار را بکند.
محتوای این فایل فقط در ویرایشگر آنلاین نمایش داده میشود؛ 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). این کار بهندرت لازم میشود (اگر اصلاً لازم شود).
