Использование MAML для концептуальной документации библиотеки [закрыто
-
21-09-2019 - |
Вопрос
Я работаю над новой библиотекой и использую комментарии XML для документации API вместе с Sandcastle, которая работает очень хорошо.
Но мне нужно написать дополнительную документацию, которая охватывает концепции, общую архитектуру, рабочие демоверсии и т. Д., Диаграммы классов и т. Д.
У меня есть 2 варианта:
- Используйте вики -двигатель и напишите документацию в стиле вики.
- Используйте MAML, который, кажется, для этой цели.
Использование вики кажется безопасным решением, потому что существует много стабильных, популярных и бесплатных двигателей, но API и концептуальная документация не пойдут рука об руку (сшивание, внешний вид и т. Д.). Использование MAML означает кривую обучения, и я не уверен в том, насколько она зрелая и каковы его преимущества/недостатки.
Вы использовали MAML/Wiki для этой цели и каковы были ваши знания? Что бы вы мне предложили?
Решение
Лично я люблю свободу работы с вики. На данный момент у вас есть несколько приличных вариантов редактирования MAML
Я не могу много говорить с DocProject (хотя это выглядит хорошо). Прямо сейчас я использую SHFB для слияния документации API и некоторых концептуальных документов в MAML. Редактор приличный и больше, чем достаточно для моих нужд. Я могу легко настроить содержимое и связь между моим API и концептуальными документами. Хороший ресурс для примеров Sandcastlestyles.
Как и во всем, есть несколько важных вопросов, которые нужно задать.
- Есть ли у вас какие -либо требования по доставке документации в одном пакете? В моем случае мне нужно было отправить все в одну красивую скомпилированную упаковку. Вы не можете сделать это с вики, но вы можете сделать это с песком.
- Собираетесь ли вы быть единственным человеком, обновляющим концептуальный контент? У большинства вики действительно хороший редактор и возможность быстро связать между темами. Единственный инструмент, необходимый для редактирования контента,-это браузер, который может быть требованием для менее технически подкованного писателя.