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

Question

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

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

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

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

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

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

Answer 1

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

• Докпроект
• Сборщик справочных файлов Sandcastle

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

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

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