Pull to refresh
  • by relevance
  • by date
  • by rating

Использование asciidoc для документирования проекта

Project management *
Когда перед нашей фрилансерской группой встала задача документирования проекта, были сформулированы следущие требования:
  • Как известно, программисты, обычно, не очень любят писать документацию… поэтому чем проще и комфортнее будет её писать, тем больше вероятность, что её таки будут писать.
    • Поскольку мы работаем из дома, то должна быть возможность писать документацию локально, на своей машине.
    • Чтобы это было делать комфортно, нужна возможность использовать для этого любимый текстовый редактор, никаких форм на вебсайтах а-ля вики или систем заточенных под конкретный редактор/IDE.
    • С доступом в инет у всех по-разному, и чтобы исключить ситуацию, когда документация небыла написана исключительно потому, что когда появилось настроение её писать по закону подлости отвалился инет — для написания документации не должен требоваться инет.
  • Документация должна быть доступна всем, кто работает над проектом. Это включает как возможность читать её через вебсайт так и работать с ней как с обычными локальными файлами.
  • Желательно, чтобы документация поддерживала какой-нить язык разметки и гиперссылки, чтобы её было удобно читать.
  • Возможность редактировать документацию из браузера (а-ля вики) желательна, но не очень важна (разработчики будут работать с файлами, так что эта фича может пригодиться в основном клиенту, который врядли будет напрямую править документацию).

Читать дальше →
Total votes 29: ↑27 and ↓2 +25
Views 21K
Comments 22

FB2 Backend к AsciiDoc

Lumber room

Предыстория



С форматом FictionBook 2 отношения у меня изначально были сложные: сначала я его не признавал, потом допускал, как исходный материал для формирования своих книг, позже, с развитием формата и сопутствующих инструментов, он стал основой моей библиотеки.

Естественно, что одной из первых задач возникла проблема преобразования в этот формат. Из всех существующих средств ни одно меня не устроило, и для обычных художественных произведений мне было проще и быстрее сделать в своём привычном текстовом редакторе (jEdit или VIM).

Небольшими затруднениями для меня были: а) описание документа — это решалось с помощью использования шаблона; б) изображения — обычно это была обложка и её можно было добавить с помощью FB Editor'а (первого); в) сноски — они встречались не часто, понемногу, и, в принципе, зная формат, добавлялись без особых затруднений.

Некоторое время назад, появился конвертер из FB2 в PDF от KiR'а, помимо того, что это замечательный инструмент для получения pdf хорошего, почти издательского качества, это был пример использования формата DocBook, о котором я много слышал, но никак не мог начать и собрать все необходимые инструменты воедино.

DocBook, как и FictionBook — формат, основанный на технологии XML. И как для FictionBook'а его не очень удобно редактировать в своём природном формате, но, к счастью, существует такая утилита, как asciidoc, которая позволяет создать из текстового файла с довольно простой разметкой соответствующий документ в формате DocBook, html или других.

Создание fb2-backend'а



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

Читать дальше →
Total votes 2: ↑2 and ↓0 +2
Views 724
Comments 1

Семантическая разметка: LaTeX, DocBook или ???

Open source *Semantics *XML *LaTeX *XSLT *
Писал комментарий к статье и понял, что надо выносить в отдельный пост.
Как многие отмечают там в комментариях статья отстой, человек не разбирается и смешал всё в кучу, попробую поделиться своими выводами от использования разных разметок.
Читать дальше →
Total votes 15: ↑13 and ↓2 +11
Views 16K
Comments 55

Asciidoc для подготовки сложной документации

System Analysis and Design *Technical Writing *

image


В заголовке использовано слово сложной, под которым можно понимать все, что угодно. Утверждение о том, что 2 * 2 = 4, если вдуматься, тоже очень не просто. Но в данном случае всё банальнее. Речь идёт о ЕСКД, ГОСТ, ОСТ и тому подобных скучных терминах, отягчаемых бюрократической процедурой согласования.


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


Сразу решили, что попробуем сделать документацию актуальной, т.е. обойтись без покраски травы в зелёный цвет. И сразу решили, что это будет Asciidoc. Почему? Потому что из текстовых языков разметки для подготовки документации он наиболее функциональный, а разворачивать неповоротливые DITA и Docbook не хотелось.


Пройдя определённую боль, мы с коллегами решили ей поделиться.

Читать дальше →
Total votes 6: ↑6 and ↓0 +6
Views 4.9K
Comments 15

AsciiDoc как стандарт для подготовки документации

Technical Writing *

ishhi puti uluchsheniya


Ключевым фактором для по-настоящему массового продукта является простота использования, функциональность и стоимость. Как принципиальный сторонник бесплатного ПО я являюсь давним пользователем технологии АsciiDoc и считаю, что на сегодняшний день она располагает самым большим потенциалом.


Функциональность Markdown и даже reStructuredText ограничена, а порог входа для DocBook и DITA достаточно высок, чтобы поставить на них крест как на массовом продукте. Нужна золотая середина между функциональностью и простотой. Система документации должна быть одинаково удобна на всех этапах жизненного цикла программного продукта: проектирование, реализация, сопровождение. В идеале она должна прекрасно применяться и вне задач создания программных продуктов.


Основной проблемой, с которой я сталкивался при подготовке документации в АsciiDoc – это отсутствие полноценного конвертера в docx (MS Word) или odt (OpenOffice/LibreOffice) для сдачи документации заказчику в этих его любимых форматах. Также эти форматы очень удобны для сравнения выходных документов.

Читать дальше →
Total votes 12: ↑11 and ↓1 +10
Views 3.8K
Comments 6

Asciidoc для ЕСКД

Technical Writing *

image


Введение


В этой статье хочу рассмотреть возможности Asciidoc в части обеспечения требований соответствия документов требованиям единой системы конструкторской документации (ЕСКД), конкретно ГОСТ Р 2.105—9 (далее ГОСТ ЕСКД). Почему именно Asciidoc, я писал здесь.


Сразу уточню. Вопрос форматирования документа здесь не рассматривается. Создающий документацию не должен задумываться о форматировании. Как системный аналитик я создаю содержание и контролирую его структуру. Для получения документа, соответствующего ГОСТ ЕСКД или другому аналогичному стандарту, я должен нажать кнопку и получить корректно отформатированный документ в любых требуемых вариантах: pdf, Open Document (Libre
Office/Open Office), Open XML (Microsoft Word) и прочих.


После работы над https://github.com/CourseOrchestra/asciidoctor-open-document уверен,
что все проблемы форматирования решаются адекватными усилиями.


Рассмотрим структуру документа Asciidoc, соответствующего требованиям
ГОСТ ЕСКД.

Читать дальше →
Total votes 11: ↑11 and ↓0 +11
Views 4.9K
Comments 8

Автоматическая генерация технической документации

XSLT *Technical Writing *

dmgtlqavf9vvl30g8hbtnyirxjo


Продолжая тему использования Asciidoc (и других аналогичных форматов) для организации процессов непрерывного документирования, хочу рассмотреть тему автоматический генерации технической документации.


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

Читать дальше →
Total votes 8: ↑7 and ↓1 +6
Views 4.8K
Comments 6

Новая документация Docsvision ч. 2 — Antora

Website development *System Analysis and Design *Development Management *Technical Writing *

Привет всем читающим! Меня зовут Владимир, я - технический писатель в компании Docsvision и я здесь, чтобы опубликовать вторую часть статьи и надрать задницу всем, кто ставил дизлайки к первой части. Статью вы можете найти ниже.

В первой статье я рассказал, как мы выбирали SSG для создания новой документации и как нам пришлось конвертировать DITA сначала в HTML, а потом в AsciiDoc.

В этой статье я расскажу, как я начал работать с SSG Antora, как я настраивал UI и добавлял сквозной поиск по сайту.

Читать далее
Total votes 7: ↑6 and ↓1 +5
Views 655
Comments 2