Comments 33
Хорошая идея. Буду иметь ввиду и такой вариант.
1) Вы используете CI сервер для сборки документации? Если да, то, какой?
2) Есть ли задача (и решение) сборки документа из частей, разложенным по разным репозитариям?
3) Есть ли версии у собираемых документов? например, разные версии ОС, для которой собирается документируемое приложение?
4) Есть ли задача поддержки многих языков документа?
Кстати, на проблему с шрифтами в FOP я тоже, в свое время потратил кучку времени, но оказалось, что делается это относительно просто. Для DITA / DITA-OT. Несмотря на это выбор XEP — одобряю.
2) Есть ли задача (и решение) сборки документа из частей, разложенным по разным репозитариям?
3) Есть ли версии у собираемых документов? например, разные версии ОС, для которой собирается документируемое приложение?
4) Есть ли задача поддержки многих языков документа?
Кстати, на проблему с шрифтами в FOP я тоже, в свое время потратил кучку времени, но оказалось, что делается это относительно просто. Для DITA / DITA-OT. Несмотря на это выбор XEP — одобряю.
1) Используем — TeamCity
2) Такой задачи пока не возникало
3) У нас есть версии по продуктам — то есть некоторые главы документов один в один идут в разные документы, часть по кускам + профайлинг что бы скрыть лишнее содержимое
4) Нет, такой задачи нет.
2) Такой задачи пока не возникало
3) У нас есть версии по продуктам — то есть некоторые главы документов один в один идут в разные документы, часть по кускам + профайлинг что бы скрыть лишнее содержимое
4) Нет, такой задачи нет.
Кстати, вопрос, если еще этим занимаетесь — а каким плагином пользовались для сборки на TC, какой-то самописный или этот вот?
А то у нас сейчас постепенно встает вопрос оптимизации сборки (используется самописная система на питоне), потому что 2 с лишним часа на полный документ это уже за гранью.
А то у нас сейчас постепенно встает вопрос оптимизации сборки (используется самописная система на питоне), потому что 2 с лишним часа на полный документ это уже за гранью.
Знакомые умудрились по ГОСТу оформить документацию в докбуке
еще вопрос: а какие среды для разработки документов смотрели?
Я рекомендую таки попробовать специализированные CSS-based XML редакторы. Моя любовь (не сочтите за рекламу): oXygen Author. Не дешевый. Но очень сильный. Есть также XMLMind, XMetaL, ArborText.
Я рекомендую таки попробовать специализированные CSS-based XML редакторы. Моя любовь (не сочтите за рекламу): oXygen Author. Не дешевый. Но очень сильный. Есть также XMLMind, XMetaL, ArborText.
Не смотрели AsciiDoc?
Он позволяет писать в удобном текстовом формате, который потом преобразовывается в DocBook.
Также можно его запускать для куска текста, что удобно, чтобы править DocBook'и напрямую.
Он позволяет писать в удобном текстовом формате, который потом преобразовывается в DocBook.
Также можно его запускать для куска текста, что удобно, чтобы править DocBook'и напрямую.
Ну я так понимаю, что AsciiDoc промежуточное звено между Plain текстом и DocBook?
Честно говоря нет. У нас документацию пишут программисты, поэтому все себя и так комфортно чувствуют при работе с XML.
Непосредственно «ввод тегов», по моему мнению, занимает настолько небольшой процент времени при написании текста — что нет смысла его избегать.
Если бы нам удалось подключить к «DocBook» не технических специалистов, то наверно в этом переходном звене был бы смысл…
Честно говоря нет. У нас документацию пишут программисты, поэтому все себя и так комфортно чувствуют при работе с XML.
Непосредственно «ввод тегов», по моему мнению, занимает настолько небольшой процент времени при написании текста — что нет смысла его избегать.
Если бы нам удалось подключить к «DocBook» не технических специалистов, то наверно в этом переходном звене был бы смысл…
Рассматривали вариант inline документации прямо в коде?
Есть аналогичный и не менее мощный вариант — LaTeX + LyX. Докбук может стать проблемой, если в команде разработчиков есть ещё и технические писатели, которым в XML разбираться будет крайне некомфортно. LyX же имеет графический интерфейс и плагины экспорта в тот же DocBook, но главное — движок TeX-а. Недостаток — исходник практически нечитабелен, и в случае конфликта…
Другой возможный вариант — fodt (Open Document Format в чистом XML-е), его поддерживает LibreOffice — в особых случаях, когда нет возможности отказаться от вордоподобного интерфейса. Тут получается полноценный ворд-редактор и формат, относительно дружественный к VCS. Пляски стилей при этом останутся, зато самый щадящий режим для зажатых со всех сторон виндовыми форматами разработчиков, когда не отвертеться и вынь да положь *.doc.
Комментарий этот к тому, что недостаёт сравнения с аналогами. По самому докбуку — стоит добавить, что есть ещё проект publican, насколько знаю, его использует в Red Hat — набор решений для выпуска готовых к печати книг (PDF) + HTML-онлайн версии из одного исходника.
Но радует, что не благодаря, а вопреки «офисный» режим постепенно сходит на нет:)
Другой возможный вариант — fodt (Open Document Format в чистом XML-е), его поддерживает LibreOffice — в особых случаях, когда нет возможности отказаться от вордоподобного интерфейса. Тут получается полноценный ворд-редактор и формат, относительно дружественный к VCS. Пляски стилей при этом останутся, зато самый щадящий режим для зажатых со всех сторон виндовыми форматами разработчиков, когда не отвертеться и вынь да положь *.doc.
Комментарий этот к тому, что недостаёт сравнения с аналогами. По самому докбуку — стоит добавить, что есть ещё проект publican, насколько знаю, его использует в Red Hat — набор решений для выпуска готовых к печати книг (PDF) + HTML-онлайн версии из одного исходника.
Но радует, что не благодаря, а вопреки «офисный» режим постепенно сходит на нет:)
Другой возможный вариант — fodt (Open Document Format в чистом XML-е)
Того же эффекта позволяет достичь использование WordML. И кстати, DocBook даже позволяет выгружать в него(но на наших документах он почему-то спотыкается).
Если передать документ нужно только для просмотра\правки, то можно перевести DocBook в rtf (DocBook->fo->rtf). Обратно, к сожалению, придется переносить изменения в ручную. Плюс, проверяющая сторона скорее всего будет ворчать на форматирование, так как fo полностью съедает логическое представление документа.
А у нас небольшой велосипед на базе DocBook. Покуда дока пишется тоже в «блокнотике» с ручным форматированием, некоторые тэги DocBook набирать просто лень. Поэтому пишем «франкенштейна», которого потом пихаем в docbook-xsl через предварительную команду вроде такой:
sed -r 's/<b>/<emphasis role="bold">/g;s/<\/b>/<\/emphasis>/g;... | xsltproc...
А есть WYSIWYG редакторы для этого формата?
У нас похоже. А в чем диаграммы рисуете? ditaa, plantuml или что-то еще?
В результате продолжительного поиска мы поняли, что решений, удовлетворяющим нашим требованиям, существует не так уж и много: DITA и DocBook. DITA сразу нам показался слишком «мощным» и сложным для перехода, а вот на DocBook мы решили остановится.
Когда-то давно занимался документацией и мне казалось что DITA — это наоборот более простой по сравнению с DocBook подход. Syntext Serna была конечно довольно крутой штукой.
Отступлю от темы: На примере документации php.net могу отметить, что при использовании docbook очень трудно организовать удобную переводимость документации.
Я вот не понимаю эту всеобщую любовь к XML-документированию. У нас в отдел выпуска программной документации купили Arbortext — на первый (второй и третий) взгляд говно.
Во-первых, XML — не самый читабельный формат. Именно поэтому даже в обычной прогерской жизни многие стараются использовать JSON.
Во-вторых, никто не знает всех этих тегов. И если программистам тут все достаточно понятно, то девочкам, которые всю жизнь щелкали по кнопкам ворда, будет крайне сложно объяснить весь дзен работы в текстовом редакторе с набором неизвестным им тегов. Ага, устроить фаталити и поставить Vim.
В-третьих, хоть и в некоторой мере решается проблема с мержами, но если вдруг есть конфликт — та еще боль мержить XML-файлы.
В-четвертых, проблема с перегоном в паблишт форматы. Ну что за дела — пляски с бубном для получения PDF?
Я не понимаю, почему никто (никто ли?) не использует для этих целей LaTeX?
Во-первых, (бывшие) студенты технических вузов с очень высокой вероятностью знают LaTeX. Для незнающих — очень простой порог вхождения, хватит дня, чтобы начать уверенно пользоваться большинством функционала в типичных ситуациях. Плюс тонны документации, в т.ч. на русском языке (опять же, для программистов это не самый важный пункт, но об английском могут совершенно ничего не знать в отделе документации).
Во-вторых, естественный синтаксис. Никакой тонны непонятных тегов — общие стили описаны где-то вне файла (или в начале), по ходу набора документации нужно просто писать текст и ничего более. Ну сравните.
В-третьих, предметный указатель, оглавление, правильные колонтитулы, сноски и многое другое доступны сразу из коробки.
В-четвертых, свободно распространяемые стили для ЕСКД и других гостовских документов. Скачал и используй, практически из коробки.
В-пятых, если в документации есть формулы (а у нас, например, такого добра навалом), то я даже не знаю, что, кроме TeX'а, можно использовать, чтобы это хотя бы хорошо выглядело.
В-шестых, на выходе получается документ с отличным оформлением, с отличными шрифтами, с типографской версткой. Помню, еще в университетские годы, когда сдавал всякие работы по физике, сразу ловил взгляды уважения за правильное и качественное оформление работы. А в МГУ, например, кроме TeX вообще ни в чем нельзя сдавать работы.
В-седьмых, есть нормальные WYSIWYG редакторы (скриншот выше).
В общем, я бы порекомендовал для всяких конструкторский документации использовать LaTeX.
А код отлично документируется Doxygen — программисту это куда ближе, чем листать аналогичную документацию в, например, pdf.
За хорошую статью автору определенно большое спасибо!
Во-первых, XML — не самый читабельный формат. Именно поэтому даже в обычной прогерской жизни многие стараются использовать JSON.
Во-вторых, никто не знает всех этих тегов. И если программистам тут все достаточно понятно, то девочкам, которые всю жизнь щелкали по кнопкам ворда, будет крайне сложно объяснить весь дзен работы в текстовом редакторе с набором неизвестным им тегов. Ага, устроить фаталити и поставить Vim.
В-третьих, хоть и в некоторой мере решается проблема с мержами, но если вдруг есть конфликт — та еще боль мержить XML-файлы.
В-четвертых, проблема с перегоном в паблишт форматы. Ну что за дела — пляски с бубном для получения PDF?
Я не понимаю, почему никто (никто ли?) не использует для этих целей LaTeX?
Во-первых, (бывшие) студенты технических вузов с очень высокой вероятностью знают LaTeX. Для незнающих — очень простой порог вхождения, хватит дня, чтобы начать уверенно пользоваться большинством функционала в типичных ситуациях. Плюс тонны документации, в т.ч. на русском языке (опять же, для программистов это не самый важный пункт, но об английском могут совершенно ничего не знать в отделе документации).
Во-вторых, естественный синтаксис. Никакой тонны непонятных тегов — общие стили описаны где-то вне файла (или в начале), по ходу набора документации нужно просто писать текст и ничего более. Ну сравните.
В-третьих, предметный указатель, оглавление, правильные колонтитулы, сноски и многое другое доступны сразу из коробки.
В-четвертых, свободно распространяемые стили для ЕСКД и других гостовских документов. Скачал и используй, практически из коробки.
В-пятых, если в документации есть формулы (а у нас, например, такого добра навалом), то я даже не знаю, что, кроме TeX'а, можно использовать, чтобы это хотя бы хорошо выглядело.
В-шестых, на выходе получается документ с отличным оформлением, с отличными шрифтами, с типографской версткой. Помню, еще в университетские годы, когда сдавал всякие работы по физике, сразу ловил взгляды уважения за правильное и качественное оформление работы. А в МГУ, например, кроме TeX вообще ни в чем нельзя сдавать работы.
В-седьмых, есть нормальные WYSIWYG редакторы (скриншот выше).
В общем, я бы порекомендовал для всяких конструкторский документации использовать LaTeX.
А код отлично документируется Doxygen — программисту это куда ближе, чем листать аналогичную документацию в, например, pdf.
За хорошую статью автору определенно большое спасибо!
то девочкам, которые всю жизнь щелкали по кнопкам ворда, будет крайне сложно объяснить весь дзен работы в текстовом редакторе с набором неизвестным им тегов
Зря надеетесь, что девочки из ворда с лёгкостью освоят TeX:) Я в своё время замучился выискивать забытые скобочки и опечатки в командах. А когда дело доходит до экранирования символов и всяких листингов — пропажу можно обнаружить порой только после вычитки документа. Тут любой язык разметки — что в лоб, что по лбу — для технически неподготовленного писателя сущий ад. Особенно, если периодически устраиваются дворцовые перевороты вроде Word -> TeX -> XML…
Кстати да, раз речь пошла о LaTeX — я правильно понимаю что в DocBook для формул нужно пользоваться MathML?
Много разного перепробовал. Остановился на Sphinx. Документация пишется в разметке RestructuredText. Из коробки есть почти всё что нужно: поддержка формул в latex, диаграммы в graphviz, перекрестные ссылки, ссылки между проектами и т. д. Есть экспорт в разные форматы. Эта система заточена именно на ручное написание развесистой документации по программным проектам, а не на генерацию из кода как, например, doxygen, хотя инструменты генерации тоже есть. Система легко расширяется, и уже существет куча полезных расширений. Честно говоря, не представляю как может быть удобно писать документацию в xml после wiki-подобных разметок. Самое близкое, что приближается к sphinx — это asciidoc, и то только в обёртке asciidoctor.
Таблицы в rst верстать — повеситься же можно. Или есть какой-то лайфхак?
Geany в этом формате документацию пишет, так вот пока обновил там одну таблицу — проклял всё.
Geany в этом формате документацию пишет, так вот пока обновил там одну таблицу — проклял всё.
Для SublimeText есть плагин, который очень помогает в написании RST-разметки. Он умеет автоматически форматировать таблицы. Иногда, правда, подглючивает. :)
К тому же, помимо классических таблиц есть возможность делать упрощённые таблицы, а также таблицы из списка.
К тому же, помимо классических таблиц есть возможность делать упрощённые таблицы, а также таблицы из списка.
Ещё забыл про csv-таблицы. Ну а если все RST-таблицы не нравятся, можно использовать директиву "
.. raw:: html" и сверстать таблицы в привычном HTML. :)
После долгих поисков остановился на Markdown.
Его GFM-диалект наиболее близок к чистому, красивому интуитивно понятному исходному тексту. Количество конфликтов при слиянии разных ревизий документа минимально, так как сводится к сравнению обычного текстового файла построчно в системе контроля версий.
Формулы в программной документации пока что не использовал, но если встретятся, можно без проблем использовать, например, MathJax.
Его GFM-диалект наиболее близок к чистому, красивому интуитивно понятному исходному тексту. Количество конфликтов при слиянии разных ревизий документа минимально, так как сводится к сравнению обычного текстового файла построчно в системе контроля версий.
Формулы в программной документации пока что не использовал, но если встретятся, можно без проблем использовать, например, MathJax.
Наверняка тем, кто еще не выбрал «свою» систему документирования, будет интересно сравнить DocBook c Dita – на днях мы опубликовали похожую статью про этот стандарт. Тем более, что проблемы и решения при использовании обоих стандартов во многом совпадают.
habrahabr.ru/company/docsvision/blog/250917/
habrahabr.ru/company/docsvision/blog/250917/
Sign up to leave a comment.
Разработка документации при помощи DocBook