Algunos archivos de documentación se aplican tanto a los Ejercicios de concepto como a los Ejercicios de práctica. Estos archivos comunes a todos los ejercicios están en el directorio exercises/shared/.docs del track:
-
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)
El documento de presentación describe cómo se usan estos archivos para presentar el contenido al estudiante.
Archivo: debug.md
Propósito: Explicar cómo un estudiante que programa en el navegador puede seguir haciendo «debugging»
Presencia: Opcional
El editor del navegador no tiene ninguna función integrada para hacer debugging. Si el test runner del track admite capturar la salida de consola, el estudiante todavía puede hacer algún tipo de «debugging», y este documento explica cómo.
El contenido de este archivo solo se muestra en el editor en línea; la CLI ignorará este archivo.
Ejemplo
# 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");
```
Archivo: help.md
Propósito: Explicar cómo un estudiante puede obtener ayuda
Presencia: Obligatorio
Describe cómo puede obtener ayuda un estudiante, específicamente para este track (no para todo Exercism).
El contenido de este archivo solo lo utiliza la CLI, que lo incluye en el archivo HELP.md.
Las instrucciones deben ser breves y directas.
Puedes enlazar a recursos como canales de Gitter, foros o listas de correo: cualquier cosa que ayude a un estudiante a desbloquearse.
Los enlaces de este documento pueden solaparse con los de docs/LEARNING.md o docs/RESOURCES.md.
Este documento no debe enlazar a recursos de ayuda para todo Exercism (independientes del track), ya que esos recursos se incluirán automáticamente en el archivo HELP.md.
Ejemplo
# 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)
Archivo: representations.md
Propósito: Explica qué normalizaciones se aplican a una solución para crear su representación
Presencia: Opcional
Cuando un track ha implementado un representer, se creará una representación para cada solución enviada.
Este documento debe enumerar todas las normalizaciones que el representer aplica a una solución.
Esto ayuda al mentor a la hora de añadir comentarios de representación.
Ejemplo
# 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
Si tu track tiene un archivo docs/REPRESENTER_NORMALIZATIONS.md, te recomendamos enlazar las normalizaciones a la sección correspondiente de ese archivo.
Archivo: tests.md
Propósito: Contiene instrucciones específicas del track sobre cómo ejecutar los tests
Presencia: Obligatorio
Describe cómo ejecutar los tests de este ejercicio en concreto.
El contenido de este archivo solo lo utiliza la CLI, que lo incluye en el archivo HELP.md.
Las instrucciones deben ser breves y directas.
El archivo docs/TESTS.md puede contener una descripción más detallada de cómo ejecutar los tests.
Ejemplo
# Tests
To run the tests, run the command `dotnet test` from within the exercise directory.
Sobrescritura
Nota: esto aún no está implementado
Los ejercicios pueden sobrescribir los archivos específicos del track creando un archivo con el mismo nombre en el directorio .docs del ejercicio (p. ej. .docs/debug.md). Rara vez debería ser necesario (si acaso alguna vez).
