Alguns arquivos de documentação se aplicam tanto aos Exercícios de Conceito quanto aos Exercícios de Prática. Esses arquivos compartilhados entre exercícios ficam no diretório exercises/shared/.docs da trilha:
-
debug.md: explica como um estudante que está programando no navegador ainda pode fazer "debugging" (opcional)
-
help.md: contém instruções específicas da trilha sobre como conseguir ajuda (obrigatório)
-
representations.md: explica quais normalizações são aplicadas a uma solução para criar sua representação (opcional)
-
tests.md: contém instruções específicas da trilha sobre como executar os testes (obrigatório)
O documento de apresentação descreve como esses arquivos são usados para apresentar o conteúdo ao estudante.
Arquivo: debug.md
Propósito: Explica como um estudante que está programando no navegador ainda pode fazer "debugging"
Presença: Opcional
O editor no navegador não tem nenhum suporte a debugging integrado. Se o executor de testes da trilha conseguir capturar a saída do console, o estudante ainda pode fazer alguma forma de "debugging", e este documento explica como fazer isso.
O conteúdo deste arquivo é apenas mostrado no editor online; a CLI vai ignorar este arquivo.
Exemplo
# 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");
```
Arquivo: help.md
Propósito: Explica como um estudante pode conseguir ajuda
Presença: Obrigatório
Descreva como um estudante pode conseguir ajuda, especificamente para esta trilha (não para todo o Exercism).
O conteúdo deste arquivo é apenas usado pela CLI, que o inclui no arquivo HELP.md.
As instruções devem ser curtas e diretas.
Você pode criar links para recursos como canais do Gitter, fóruns ou listas de e-mail: qualquer coisa que ajude um estudante a se destravar.
Os links deste documento podem se sobrepor aos de docs/LEARNING.md ou docs/RESOURCES.md.
Este documento não deve conter links para recursos de ajuda gerais do Exercism (que não são específicos da trilha), pois esses recursos serão incluídos automaticamente no arquivo HELP.md.
Exemplo
# 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)
Arquivo: representations.md
Propósito: Explica quais normalizações são aplicadas a uma solução para criar sua representação
Presença: Opcional
Quando uma trilha implementa um representer, é criada uma representação para cada solução enviada.
Este documento deve listar todas as normalizações que o representer aplica a uma solução.
Isso ajuda um mentor na hora de adicionar comentários de representação.
Exemplo
# 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
Se a sua trilha tem um arquivo docs/REPRESENTER_NORMALIZATIONS.md, recomendamos criar links das normalizações para a seção correspondente desse arquivo.
Arquivo: tests.md
Propósito: Contém instruções específicas da trilha sobre como executar os testes
Presença: Obrigatório
Descreva como executar os testes deste exercício em particular.
O conteúdo deste arquivo é apenas usado pela CLI, que o inclui no arquivo HELP.md.
As instruções devem ser curtas e diretas.
O arquivo docs/TESTS.md pode conter uma descrição mais detalhada de como executar os testes.
Exemplo
# Tests
To run the tests, run the command `dotnet test` from within the exercise directory.
Sobrescrita
Observação: isso ainda não foi implementado
Os exercícios podem sobrescrever os arquivos específicos da trilha criando um arquivo com o mesmo nome no diretório .docs do exercício (por exemplo, .docs/debug.md). Isso raramente deve ser necessário (se é que será).
