Presentación

Este documento describe cómo se presentan al estudiante los distintos archivos de ejercicios y de 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 el concepto o 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 al estudiante pistas para desatascarse en un ejercicio (obligatorio en los ejercicios de concepto; opcional en los ejercicios de práctica)
  • .meta/config.json: contiene información de la fuente del ejercicio (opcional)

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

Archivos específicos del track

Estos archivos se comparten entre todos los ejercicios:

  • debug.md: explica cómo un estudiante que programa en el navegador todavía puede hacer «depuración» (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 las pruebas (obligatorio)

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

Documentación común a todo Exercism

Además de los archivos de documentación anteriores, específicos del track o del ejercicio, hay dos secciones de documentación comunes a todo Exercism (y, por lo tanto, compartidas por todos los track):

  • 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 se muestran en los momentos oportunos. Por ejemplo, las pistas no se muestran a menos que el estudiante pida verlas. Además, el editor tampoco necesita mostrar las instrucciones de la CLI.

CLI

Cuando trabajas localmente con la CLI, no tenemos la opción de mostrar la documentación de forma condicional. Por lo tanto, la CLI siempre debe descargar 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 las pruebas, además de las instrucciones de ayuda específicas del track y las comunes a todo 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.