DITA для документирования программных библиотек

Хотя это не вопрос о «программировании» DITA, я все же хотел бы задать его в сообществе stackoverflow, где большинство пользователей являются разработчиками.

Наша компания использует комбинацию Doxygen и MediaWiki для документирования библиотек программного обеспечения (например, QSchematic). Нам кажется, что MediaWiki — не лучший способ документирования программных библиотек.

Мой вопрос: стоит ли начинать использовать DITA для документирования программных библиотек? Я провел довольно много часов, работая с DITA и DITA-OT, и я думаю, что это хорошее решение для документирования программных компонентов, с которыми напрямую взаимодействуют конечные пользователи (например, инструменты командной строки). Однако я не совсем уверен, является ли DITA хорошим решением для документирования программных библиотек. После довольно большого количества исследований кажется, что DITA широко не используется разработчиками программного обеспечения (библиотек). DITA предоставляет специализацию, которая позволяет создавать пользовательские темы для этой цели, но, поскольку никто другой в Интернете, кажется, не делает этого, мне интересно, есть ли что-то принципиально неправильное в использовании DITA для этой цели.


dita
person Joel Bodenmann    schedule 08.04.2019    source источник
comment
Вы можете проверить справочный центр и Как спросить, этот вопрос не подходит для Stack Overflow.   -  person Kyll    schedule 08.04.2019
comment
Спасибо за ваш комментарий. Пока я оптимизировал заголовок вопроса. Я посмотрел в справочном центре. Я надеялся, что этот вопрос попадет под категорию software tools commonly used by programmers; [...]. Пожалуйста, дайте мне знать, где я должен разместить этот вопрос вместо этого. Я не смог найти сообщество по обмену документацией или подобным.   -  person Joel Bodenmann    schedule 08.04.2019
comment
Я считаю, что более подходящим SE для этого вопроса будет Software Rec. Обязательно прочитайте их справочный центр, чтобы понять, что представляет собой запрос инструмента на их сайте =)   -  person Kyll    schedule 08.04.2019
comment
Markdown и другие легкие языки разметки широко используются для программного обеспечения. Если вам нужна дополнительная структура и вы по-прежнему заинтересованы в DITA, посмотрите формат облегченной DITA в формате Markdown: docs.oasis-open.org/dita/LwDITA/v1.0/cn01/LwDITA-v1.0-cn01.html   -  person markg    schedule 09.04.2019
comment
Я работаю в Oxygen XML Editor, и мы используем собственный инструмент для создания руководства пользователя из контента DITA. Наш контент DITA находится в учетной записи GitHub: github.com/oxygenxml/userguide и сгенерированной HTML-документации. находится здесь: oxygenxml.com/doc/versions/21.0/ug-editor< /а>   -  person Radu Coravu    schedule 09.04.2019

Ответы (1)


arrow_upward
1
arrow_downward

DITA может подойти и предоставить все функции, которые вам нужны или могут понадобиться в будущем. Возможно, подойдет и такой инструмент, как read-the-docs или Swagger, но это зависит от документов, которые вы хотите создать, поэтому сложно ответить, не зная ваших библиотек и контента. Преимущество DITA заключается в повторном использовании и гибкости. Вы можете использовать фрагменты внешнего кода, повторно использовать части своих справочных документов в концептуальных темах и темах задач, что дает вам возможность достичь всего, что вы можете себе представить.

person Stefan Eike    schedule 26.04.2019