Presentación

Este documento describe cómo se presentan al estudiante los distintos archivos de ejercicios y del track, teniendo en cuenta si el estudiante usa la CLI o el editor.

Documentación

Hay tres tipos de documentación que determinan qué documentación se presenta para un ejercicio.

Archivos específicos del ejercicio

Estos archivos son específicos de cada ejercicio:

  • .docs/introduction.md: presenta al estudiante los conceptos que enseña el ejercicio (obligatorio)
  • .docs/introduction.append.md: texto de introducción adicional que se añade después de la introducción existente (no se usa en los ejercicios de concepto; opcional en los ejercicios de práctica)
  • .docs/instructions.md: proporciona las instrucciones del ejercicio (obligatorio)
  • .docs/instructions.append.md: texto de introducción adicional que se añade después de las instrucciones existentes (no se usa en los ejercicios de concepto; opcional en los ejercicios de práctica)
  • .docs/hints.md: proporciona pistas al estudiante para ayudarle a desatascarse en un ejercicio (obligatorio en los ejercicios de concepto; opcional en los ejercicios de práctica)
  • .meta/config.json: contiene la información de la fuente del ejercicio (opcional)

Consulta la documentación de los ejercicios de concepto y la documentación de los ejercicios de práctica para obtener más información.

Archivos específicos del track

Estos archivos son compartidos por todos los ejercicios:

  • debug.md: explica cómo un estudiante que programa en el navegador puede seguir haciendo «debugging» (opcional)
  • help.md: contiene instrucciones específicas del track sobre cómo obtener ayuda (obligatorio)
  • representations.md: explica qué normalizaciones se aplican a una solución para crear su representación (opcional)
  • tests.md: contiene instrucciones específicas del track sobre cómo ejecutar los tests (obligatorio)

Consulta la documentación de los archivos compartidos para obtener más información.

Documentación general de Exercism

Además de los archivos de documentación anteriores, específicos del track o del ejercicio, hay dos fragmentos de documentación que son generales de Exercism (y, por tanto, compartidos por todos los tracks):

  • Instrucciones sobre cómo usar la CLI para enviar un ejercicio
  • Instrucciones sobre cómo obtener ayuda

Editor

Cuando trabajas en un ejercicio en el navegador, los archivos de documentación aparecen en los momentos relevantes. Por ejemplo, las pistas no se muestran a menos que el estudiante solicite que se muestren. Además, el editor no necesita mostrar las instrucciones de la CLI.

CLI

Cuando trabajas en local a través de la CLI, no tenemos la opción de mostrar la documentación de forma condicional. Por eso, la CLI debe descargar siempre toda la documentación relevante. Para no obligar al estudiante a abrir varios archivos, la CLI concatena toda la documentación relevante en tres documentos:

README.md

Este archivo contiene las instrucciones del ejercicio, la introducción (opcional) y la información de la fuente (opcional).

# [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

Este archivo describe cómo ejecutar los tests, así como las instrucciones de ayuda específicas del track y generales de 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

Este archivo contiene las pistas específicas del ejercicio (opcional)

# Hints

## General

- Consider extracting the logic to a helper function.