Использование MAML для концептуальной документации библиотеки

Question

Я работаю над новой библиотекой и использую XML-комментарии для документации API вместе с SandCastle, который работает очень хорошо.

Но мне нужно написать дополнительную документацию, которая охватывает концепции, общую архитектуру, рабочие демонстрации и т. Д., Диаграммы классов и т. Д.

У меня есть 2 варианта:

1. Используйте некоторый вики-движок и напишите документацию в стиле вики.
2. Используйте MAML, который, кажется, для этой цели.

Использование вики кажется безопасным решением, потому что есть много стабильных, популярных и бесплатных движков, но API и концептуальная документация не идут рука об руку (перекрестные ссылки, внешний вид и т. Д.). Использование MAML означает кривую обучения, и я не уверен, насколько он зрелый и каковы его преимущества / недостатки.

Использовали ли вы MAML/Wiki для этой цели и чему научились? Что бы вы мне предложили?

Answer 1

Лично я люблю свободу работы с Wiki. На данный момент у вас есть несколько приличных вариантов для редактирования MAML

• DocProject
• Конструктор файлов справки Sandcastle

Я не могу много говорить с DocProject (хотя это выглядит красиво). Прямо сейчас я использую SHFB для объединения документации API и некоторых концептуальных документов в MAML. Редактор приличный и более чем достаточно для моих нужд. Я могу легко настроить оглавление и ссылку между моим API и концептуальными документами. Хороший ресурс, на который можно посмотреть примеры, - SandcastleStyles.

Как и во всем, есть несколько важных вопросов.

• Есть ли у вас какие-либо требования для отправки вашей документации в одной упаковке? В моем случае мне нужно было отправить все в одном хорошем скомпилированном пакете. Вы не можете сделать это с Wiki, но вы можете сделать это с Sandcastle.
• Собираетесь ли вы быть единственным человеком, который обновляет концептуальный контент? У большинства вики есть действительно хороший редактор и возможность быстро связывать темы. Единственный инструмент, который вам нужен для редактирования контента - это браузер, который может быть требованием для менее технически подкованного автора.