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

Question

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

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

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

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

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

Вы использовали MAML/Wiki для этой цели и каковы были ваши знания? Что бы вы мне посоветовали?

Answer 1

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

• DocProject
• Sandcastle Help File Builder

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

Как и во всех других вещах, есть несколько важных вопросов.

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