Создание пользовательской документации

http://sphinx-doc.org

doxygen

Пиши на ReST. Не супер, но гораздо проще DocBook.

не очень хочется разбираться в самом инструменте

Тогда ReST точно для тебя.

Для несложных мне нравятся txt2tags и Markdown.

ох и долбанутая там разметка... я бы бахнул в либре и експортнул в pdf, меньше гемору будет.

на лоре в моде латекс

в моде латекс

Из него html плохой получается. Лучше markdown. И html и pdf и в виде текста удобно читать.

Зависит от объема. Но если много страниц с рисунками, перекрестными ссылками, таблицами и прочим, то однозначно LaTeX.

http://www.methods.co.nz/asciidoc/

Про POD ещё забыли

LaTeX, из него html неплохо делает тулза hevea

DITA в той же Serna.

У нас некоторые техписатели в gedit писали DocBook, и никто не умер :-). К тому же к DocBook-у просто прикрутить l10n, см. po4a

AsciiDoc

Latex это унылое старье из 70-х

ага

А компьютер это унылое старье из XIX века. Учите матчасть.

И фу быть таким жирным и зеленым.

открой для себя языки упрощенной разметки

мы тут не научную работу пишем

Ниасилятор? Уж будьте последовательны в своих заблуждениях, или Латех «унылое г-но из 70х», или супер-пупер тулза для написания научных работ избранными.

я Латех осилял лет 10 назад.

Сейчас технологии шагнули вперед. И на прошедшей конференции Линух настоящий ажиотаж и последующий фидбэк вызвали как раз Cross Media Publishing: AsciiDoc & Co (было аж 3 доклада), а люди со стенда с Латехом как всегда скучали.

Зы. а еще есть DocBook, но только даже в нем профессиональные издатели (O'Reilly, OpenSource Press) уже не верстают, а перешли на AsciiDoc.

а вы латех, латех. Это всего лишь один из бэкендов для сабжа, ну и формулки вставлять, да;-)

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

org-mode

http://orgmode.org/worg/images/screenshots/org-mode-publishing.jpg

а вы латех, латех. Это всего лишь один из бэкендов для сабжа, ну и формулки вставлять, да;-)

Если Вы латех воспринимаете таким образом, значит 10 лет назад Вы его до конца не осилили.

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

Просветите ретрограда, и чем же все эти новомодные фуророобразующие вундервафли лучше латеха? Ниже порог вхождения? Проще использование? Автоматическая генерация каркаса документации на основе исходников (doxygen ЕМНИП умеет это в латех как раз)? Более качественная верстка по умолчанию?

Сейчас, например, все больше презентаций делают в бимере (латеховский стиль). Несмотря на 100500-ю версию повер пойнта и прочие волшебные фенечки.

Ниже порог вхождения?

да.

Проще использование?

да.

Более качественная верстка по умолчанию

да. Причем на выходе одинаково качественным должны быть как DocBook XML, так и PDF/HTLML/CHM/EPUB

вот хрена лысого такое ты в Latex сможешь.

зы. Учти, что за сабжем уже стоят СЕРЬЕЗНЫЕ издательства. А в какое издательство ты понесешь этот твой латех?

В те издетельства, которые для меня актуальны, носят именно латех. Еще носят ворд, но ему там не рады.

Зы. а еще есть DocBook, но только даже в нем профессиональные издатели (O'Reilly, OpenSource Press) уже не верстают, а перешли на AsciiDoc.

а вы латех, латех. Это всего лишь один из бэкендов для сабжа, ну и формулки вставлять, да;-)

ну дык и DocBook тоже просто бекенд вроде латеха, а писать надо в какой-то облегчённой разметке, потом если чо в DocBook конвертировать.

вроде ODF/HTML через DocBook красивее получается, чем через латех (можно, конечно, повозиться с контехом)

Сейчас технологии шагнули вперед.

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

но только даже в нем профессиональные издатели (O'Reilly, OpenSource Press) уже не верстают, а перешли на AsciiDoc.

«Профессиональные издатели» быдлокодерских буклетиков не интересуют. Вот когда издания Elsevier начнут твой asciidoc убогий принимать, тогда и поговорим. Или хотя бы когда IEEE Communications начнет статьи в asciidoc печатать.

Низкий порог вхождения может интересовать только совсем уж ничтожную, никчемную плесень.

мы тут не научную работу пишем

Я заметил, что 99% всей документации - вонючее жидкое говно. Лучше бы писали так, как пишут научные работы. Вот, например, посмотри на собственно сам TeX, который так же является документацией на TeX.

AsciiDoc

Покажи, как в этом убогом говне нарисовать простую диаграмку (например, flow chart).

Такое должно быть практически в любой документации (а если нет, то говно это неюзабельное, а не документация).

Orelly, нет?

Просветите ретрограда, и чем же все эти новомодные фуророобразующие вундервафли лучше латеха? Ниже порог вхождения? Проще использование? Автоматическая генерация каркаса документации на основе исходников (doxygen ЕМНИП умеет это в латех как раз)? Более качественная верстка по умолчанию?

специяльно для ретроградов, ссылко

поклацайте там : слева в окошке выберите Report/chapter-01.txt, повтыкайте на контент в окошке справа, понажимайте кнопачки Export as PDF/latex, попытайтесь понаписать чего то своё, сохранить/загрузить локально на диск

чуёте, чем дело пахнет? полный вебдваноль, прыщавая молодёжь и никакого софта не надо на клиентской машине, чтобы книжке писать. они даже энтот нотех скачивать дают в виде виртуалки, вот до чего техника дошла на лыжах

Сейчас, например, все больше презентаций делают в бимере (латеховский стиль).

это да. но можно и в контехе и в оргмоде, или как прыщавая молодёжь, сразу в медиавики с S3 плагином со слайдами на HTML5

а скрипач не то чтобы очень уж незаменимый.

я бы вот с радостью заменил где можно на какую-нибудь скриблю, или по ссылкам со скрибли, и какую-нибудь literate programming / reproducible research среду типа org-mode, а в качестве бекенда скриблю/lout/nonpareil или просто оргмоде.

lout/nonpareil как то концептуально чище для меня, ну как фрибзд. чисто из любви к искусству.

а латех/линух со 150 дистрибутивов на 1050 пакетов на 10500 случаев жизни — практичнее, да.

вот хрена лысого такое ты в Latex сможешь.

не сможешь в латехе — бери контех, там как-то вывод покачественнее иногда.

Покажи, как в этом убогом говне нарисовать простую диаграмку (например, flow chart).

ты не поверишь, но они упоролись со своим питоном

ну в орг-моде как-то проще это всё. хренячим chunk с выводом plantuml / чего-то ещё в картинку, вставляем картинку, генерим картинку в нужном виде (пиксельная или векторная).

т.е. это не прерогатива исключительно теха. вон в lout графики из коробки чертить можно, без всяких пакетов.

ах, да, можно ещё в емаксе асци графикой UML диаграмму рисовать, и втыкать в ascidoc, но это уже спец. олимпиада.

конкретно для asciidoc, а не сфинкса

мы тут не научную работу пишем

Я заметил, что 99% всей документации - вонючее жидкое говно. Лучше бы писали так, как пишут научные работы.

+стоадинаццадь.

всем программистам-документаторам срочно читатьстатью про reproducible research и повтыкать в проектик на org-mode, чтобы понять как это к своему случаю можно применить.

документация — это не хрен собачий. её писать надо вдумчиво, с разумением, нетлёнку для читателя, а не необновлямое write only и навыкид.

ладно бы ещё инструментов не было, одна токмо клинопись. но есть же давным-давно, зачем же выдавать шлак ибо «тихналогию ниасилил»?

фу.. Emacs, Org-Mode, Lisp....

извращенцы...

и чо?

ты суть улови: твой мегауникальный рисёрч это по сути всего несколько файлов в CSV.

и грамотная WEB среда в org-mode, которая делает всю расчётку, и красиво верстает.

а всё что можно запрограммировать — нужно запрограммировать один раз и забыть об этом, не терять время на мелочи, но сконцентироваться на сути работы.

возьмём к примеру, проект openwatcom.

NIH синдром во все поля — они родили свою troff-подобную утилиту для генерации ps, pdf, html, chm, OS/2 .inf и прочая, прочая.

с одной стороны, single source: правим хелп в своём NIH-формате, на выходе имеем качественную документацию под все системы сразу.

с другой стороны, это NIH сослужило плохую службу, nach.

ибо язык разметки — свой собственный уникальный, утилитка бинарная и под дос то ли на форте, то ли на асме, сорцы давно про*баны за давностию лет.

и сейчас эти уникумы пытаются реверсить свой уникальный формат, чтобы из него родить конвертор NIH разметки во что-то более современное.

ИМХО, проще сразу переписать доку на том же сфинксе, хотя бы.

да, это много тупой скучной работы, но сделать её надо один раз. вона в сообчестве opendylan так уже почти все книжки и переписали, а там их штук пять страниц по пиццот. и новая инфа появляется, сразу в сфинксе

тут главное среду правильно выбрать, чтобы автоматизировать в дальнейшем было просто всё что только можно

ты не поверишь, но они упоролись со своим питоном

Ну, то есть, руками рисовать. А надо автоматически dependency graph из CMake выдавить, например.

Ты рассказывай, как flow chart нарисовать. Без рукоблудия.

Спасибо, забавно. Меня всегда умиляло, как такие вот кулибины от ИТ ваяя очередную вундервафлю первым делом выдумывают новый «упрощенный» синтаксис. А потом пользователю, случайно выучившему че нить нормальное навроде латеха, приходиться учить еще новую «упрощенную» разметку.

Пожалуй и дальше буду ретроградствовать;-)

приходиться учить еще новую «упрощенную» разметку

а что там «учить»?

вроде бы просто всё, сел и поехал

Меня всегда умиляло, как такие вот кулибины от ИТ ваяя очередную вундервафлю первым делом выдумывают новый «упрощенный» синтаксис.

ну я понимаю это так, что упрощённый синтаксис — это таки добро, потому что писателю проще начать, просто сесть и начать писать.

«как стать писателем — берите ручку и пишите», да.

всё таки, в латехе тоже нужно «учить разметку», привыкать как верстать таблицы, учить много неконсистентных между собой команд, (в отличие от того же контеха или skribilo), обрастать рецептами всяких стандартных пакетов, хаков, стилей, и воркэраундов; цепочку конверторов подобрать, чтобы результат не выглядел как говно

в отличие, от того же skribilo с outline синтаксисом (org-mode упрощённый) ,например, да или просто org-mode  — «сел и поехал». не хватило простой разметки — взял skribe define-syntax reader, или свой написал. не хватило функциональности — взял, написал что нужно тут же, на схеме.

а уже в конкретный латех/контех/HTML/xml/odf=xml+xslt/дописать свой writer — пускай инструмент конвертирует.

другое дело, что «изучение латеха» — это как изучение вима или емакса: выучил его лет пятнадцать назад, и уверен что следущие лет 30 там принципиально ничего не изменится :))

и сейчас эти уникумы пытаются реверсить свой уникальный формат, чтобы из него родить конвертор NIH разметки во что-то более современное.

прозреваю, что тут можно справиться, если взять skribilo, дописать свой reader на этот «отреверсенный NIH формат» (там что-то постскрипт-подобное, ЕМНИП), и уже скриблей сконвертировать во что-то более прозрачное.

однако, факт: вот 2 системы подготовки документации, из которых во второй (сфинкс + rst) документацию писать явно легче и проще.

Ну, то есть, руками рисовать. А надо автоматически dependency graph из CMake выдавить, например.

я так понимаю, это «зе пистон сфинкстор вей»: вместо того, чтобы сгенерировать картинку в каком-то универсальном формате типа METAPOST/tikz/dot/... или как в org-mode babel не парясь, вызывают plantuml/yEd/свой наколеночный скрипт, они пишут стопиццот плагинов на все случаи жызни, визиторы-шмизиторы в плагинах и свой очередной велосипедный синтаксис в плагине.

скрибли на них нет, с доступными для схемы AST-преобразованиями, define-reader и writer-ами

иными словами, тезис:

системы с упрощённой разметкой лучше тем, что:

• разметка проще:
  • понятнее: учить ascii-art разметку меньше чем теги+команды
  • целостнее: «команды» или их отсутствие устроены однотипно
  • прозрачнее: ascii-арт типа org-mode меньше бросается в глаза.

    проще написать * FOO \** BAR \ *** BAZ чем \chapter{FOO} \section{BAR} \subsubsection{BAZ}

    хотя это вкусовщина, из разряда «лисп это куча скобок»

• разметка функциональнее:
  • к примеру, вики-ссылки или «захваченные» ссылки в org-mode.

    в latex/html/skribe нужно:

    • поставить якорь, поставить ссылку - 2 действия
    • cледить за уникальностью ссылок и т.п.
    в вики-разметке нужно:
    • поставить ссылку особого рода, из которой можно перейти или редактировать
    • не думать о якорях, только о вики-ссылках
    • в идеале, хочется несколько типов ссылок, типа «семантической вики»
• система функциональнее+расширяемее:
  • конвертация в большее число форматов
  • более прозрачный процесс конвертации и более качественный результат
  • в идеале, расширяемость AST преобразованиями
  • в идеале, плагины и батарейки из коробки

итого проще начать работу и получить результат.

другое дело, что и org-mode babel + конвертация в tex + ручное допиливание стилей tex и скриптов в тулчейне тоже неплохо справляются

срочно читать статью про reproducible research и повтыкать в проектик на org-mode

пример не полный без ссылки на проект к статье (via) (cм. также)

подборка по семантическим вики:

разработка документации, управление знаниями

спецификация бизнес-процессов

моделирование энтырпрайз процессов и приложений

управление качеством в разработке ПО

обработка ЕЯ(естетв.языка) 1 2

разработка БП

ынтырпрайс процессный движок

научный workflow и семантические вики

last but not least редактор БП

подобный workflow вполне можно выстроить используя org-mode babel + какой-то набор скриптов вместо semantic wiki.

или skribilo расширять каким-то «сематническим DSL» на схеме.

подобный workflow вполне можно выстроить используя org-mode babel + какой-то набор скриптов вместо semantic wiki.

вот пример http://gnowgi.org/tag/wiki/

http://gnowgi.org/2013/02/18/metastudio-and-orgmode/

алсо GNOSYS-mode GNOSYS

публикации