Algunos archivos de documentación se aplican tanto a los ejercicios de concepto como a los ejercicios de práctica. Estos archivos compartidos entre ejercicios se encuentran en el directorio exercises/shared/.docs del track:
-
debug.md: explica cómo un estudiante que programa en el navegador todavía puede hacer «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 las pruebas (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 todavía puede hacer «debugging»
Presencia: opcional
El editor del navegador no tiene soporte de debugging integrado. Si el ejecutor de pruebas del track admite capturar la salida de consola, el estudiante todavía puede hacer alguna forma de «debugging» y este documento explica cómo.
El contenido de este archivo se muestra solo 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 un estudiante puede obtener ayuda, específicamente para este track (no de todo Exercism).
El contenido de este archivo solo lo usa 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 salir del bloqueo.
Los enlaces de este documento pueden coincidir con los de docs/LEARNING.md o docs/RESOURCES.md.
Este documento no debe enlazar a recursos de ayuda generales de 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 crea 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 a un mentor cuando añade 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 las pruebas
Presencia: obligatorio
Describe cómo ejecutar las pruebas de este ejercicio en particular.
El contenido de este archivo solo lo usa 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 las pruebas.
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 (por ejemplo, .docs/debug.md). Esto rara vez debería ser necesario (si acaso alguna vez).
