DITA для документирования программных библиотек
Хотя это не вопрос о «программировании» DITA, я все же хотел бы задать его в сообществе stackoverflow, где большинство пользователей являются разработчиками.
Наша компания использует комбинацию Doxygen и MediaWiki для документирования библиотек программного обеспечения (например, QСхематик). Нам кажется, что MediaWiki — не лучший способ документирования программных библиотек.
Мой вопрос: стоит ли начинать использовать DITA для документирования программных библиотек? Я провел довольно много часов, работая с DITA и DITA-OT, и я думаю, что это хорошее решение для документирования программных компонентов, с которыми напрямую взаимодействуют конечные пользователи (например, инструменты командной строки). Однако я не совсем уверен, является ли DITA хорошим решением для документирования программных библиотек. После довольно большого количества исследований кажется, что DITA широко не используется разработчиками программного обеспечения (библиотек). DITA предоставляет специализацию, которая позволяет создавать пользовательские темы для этой цели, но, поскольку никто другой в Интернете, кажется, не делает этого, мне интересно, есть ли что-то принципиально неправильное в использовании DITA для этой цели.
Спасибо за ваш комментарий. Пока я оптимизировал заголовок вопроса. Я посмотрел в справочном центре. Я надеялся, что этот вопрос попадет в категорию software tools commonly used by programmers; [...]. Пожалуйста, дайте мне знать, где я должен разместить этот вопрос вместо этого. Я не смог найти сообщество по обмену документацией или подобным.
Я считаю, что более подходящим SE для этого вопроса будет Рекомендации по программному обеспечению. Обязательно прочитайте их справочный центр, чтобы понять, что представляет собой запрос инструмента на их сайте =)
Markdown и другие легкие языки разметки широко используются для программного обеспечения. Если вы хотите больше структуры и по-прежнему заинтересованы в DITA, посмотрите на формат Markdown облегченного DITA: docs.oasis-open.org/dita/LwDITA/v1.0/cn01/LwDITA-v1.0-cn01.html.
Я работаю в Oxygen XML Editor, и мы используем собственный инструмент для создания руководства пользователя из контента DITA. Наш контент DITA находится в учетной записи GitHub: github.com/oxygenxml/userguide, а сгенерированная HTML-документация находится здесь: oxyxml.com/doc/versions/21.0/ug-редактор.
Ответы 1
DITA может подойти и предоставить все функции, которые вам нужны или могут понадобиться в будущем. Возможно, подойдет и такой инструмент, как read-the-docs или Swagger, но это зависит от документов, которые вы хотите создать, поэтому сложно ответить, не зная ваших библиотек и контента. Преимущество DITA заключается в повторном использовании и гибкости. Вы можете использовать фрагменты внешнего кода, повторно использовать части своих справочных документов в концептуальных темах и темах задач, что дает вам возможность достичь всего, что вы можете себе представить.
Возможно, вы захотите проверить центр помощи и Как спросить, этот вопрос не подходит для переполнения стека.