ارائه

این سند توضیح می‌دهد که فایل‌های گوناگون تمرین و مسیر چگونه به زبان‌آموز ارائه می‌شوند و در این میان، اینکه زبان‌آموز از CLI استفاده می‌کند یا از ویرایشگر، در نظر گرفته می‌شود.

مستندات

سه نوع مستند وجود دارد که تعیین می‌کند چه مستنداتی برای یک تمرین ارائه می‌شود.

فایل‌های مخصوص تمرین

این فایل‌ها مخصوص هر تمرین هستند:

• .docs/introduction.md: مفهوم یا مفاهیمی را که تمرین به زبان‌آموز می‌آموزد معرفی می‌کند (الزامی)
• .docs/introduction.append.md: متن مقدمه‌ی اضافی که بعد از مقدمه‌ی موجود افزوده می‌شود (در تمرین‌های مفهومی استفاده نمی‌شود، برای تمرین‌های عملی اختیاری است)
• .docs/instructions.md: دستورالعمل‌های تمرین را ارائه می‌دهد (الزامی)
• .docs/instructions.append.md: متن مقدمه‌ی اضافی که بعد از دستورالعمل‌های موجود افزوده می‌شود (در تمرین‌های مفهومی استفاده نمی‌شود، برای تمرین‌های عملی اختیاری است)
• .docs/hints.md: راهنمایی‌هایی در اختیار زبان‌آموز می‌گذارد تا وقتی در تمرین گیر می‌کند، خودش بتواند از بن‌بست بیرون بیاید (برای تمرین‌های مفهومی الزامی، برای تمرین‌های عملی اختیاری)
• .meta/config.json: اطلاعات منبع تمرین را در خود دارد (اختیاری)

برای اطلاعات بیشتر، مستندات تمرین‌های مفهومی و مستندات تمرین‌های عملی را ببینید.

فایل‌های مخصوص مسیر

این فایل‌ها میان همه‌ی تمرین‌ها مشترک‌اند:

• debug.md: توضیح می‌دهد زبان‌آموزی که در مرورگر برنامه‌نویسی می‌کند چطور می‌تواند همچنان debug کند (اختیاری)
• help.md: دستورالعمل‌های مخصوص مسیر درباره‌ی نحوه‌ی گرفتن کمک را در خود دارد (الزامی)
• representations.md: توضیح می‌دهد برای ساختن بازنمایی یک راه‌حل، چه نرمال‌سازی‌هایی روی آن اعمال می‌شود (اختیاری)
• tests.md: دستورالعمل‌های مخصوص مسیر درباره‌ی نحوه‌ی اجرای testها را در خود دارد (الزامی)

برای اطلاعات بیشتر، مستندات فایل‌های مشترک را ببینید.

مستندات سراسری 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

این فایل نحوه‌ی اجرای testها و همچنین دستورالعمل‌های کمک مخصوص مسیر و سراسری 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.