Usando MAML para documentação conceitual da biblioteca [fechado
https://stackoverflow.com/questions/1573574
-
21-09-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianPergunta
Estou trabalhando em uma nova biblioteca e estou usando comentários XML para documentação da API junto com o Sandcastle, que funciona muito bem.
Mas preciso escrever documentação adicional que abranja conceitos, arquitetura geral, demos de trabalho etc., diagramas de classes etc.
Eu tenho 2 opções:
- Use algum mecanismo wiki e escreva o estilo wiki de documentação.
- Use Maml, que parece ser para esse fim.
O uso do wiki parece uma solução segura porque existem muitos motores estáveis, populares e gratuitos disponíveis, mas a API e a documentação conceitual não andam de mãos dadas (reticulação, aparência etc.). Usar MAML significa uma curva de aprendizado e não tenho certeza de como é madura e quais são suas vantagens/desvantagens.
Você já usou Maml/Wiki para esse fim e quais foram seus aprendizados? O que você me sugeriria?
Solução
Pessoalmente, eu amo a liberdade de trabalhar com um wiki. Neste ponto, você tem algumas opções decentes para editar maml
Não posso falar muito com o DocProject (embora pareça bom). No momento, estou usando o SHFB para mesclar a documentação da API e alguns documentos conceituais no MAML. O editor é decente e mais do que suficiente para minhas necessidades. Consigo configurar facilmente um índice e link entre minha API e documentos conceituais. Um bom recurso a se olhar para exemplos é Sandcastlestyles.
Como em todas as coisas, há algumas perguntas importantes a fazer.
- Você tem algum requisito para enviar sua documentação em um pacote? No meu caso, eu precisava enviar tudo em um belo pacote compilado. Você não pode fazer isso com um wiki, mas pode fazer isso com castelo de areia.
- Você será a única pessoa que atualiza o conteúdo conceitual? A maioria dos wikis tem um editor muito bom e uma capacidade de vincular rapidamente os tópicos. A única ferramenta necessária para editar o conteúdo é um navegador, o que pode ser um requisito para um escritor menos tecnicamente experiente.
