Pull to refresh
28
Karma
8
Rating
Поташников Николай Михайлович @fiddle-de-dee

Системный аналитик

  • Followers 17
  • Following 3

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

XSLT *Technical Writing *

dmgtlqavf9vvl30g8hbtnyirxjo


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


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

Читать дальше →
Total votes 8: ↑7 and ↓1 +6
Views 4.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

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

Бюрократизация IT

Technical Writing *


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


Вопрос заключается в том, обеспечивает ли такое количество документации надлежащее качество выполненных работ?


Для тех, кто в теме, давно уже не секрет, что громадное количество «макулатуры», сдаваемой заказчику, часто служит прикрытием творческой несостоятельности заказчика или разработчика, которые не могут правильно поставить задачу и сделать качественный продукт и прикрывают это объёмом технической документации. «Макулатура» также служит обоснованием завышенной стоимости программного продукта.


Чиновника это устраивает, так как при любой проверке можно показать объём странице-километров документации и избежать ответственности за неработающее программное обеспечение.

Читать дальше →
Total votes 12: ↑10 and ↓2 +8
Views 3.3K
Comments 22

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

PlantUML — все, что нужно бизнес-аналитику для создания диаграмм в программной документации

System Analysis and Design *UML Design *Development Management *Project management *

Введение


Я — системный аналитик, и моя работа заключается в том, чтобы проектировать автоматизированные информационные системы. Впрочем, нет, она заключается в том, чтобы писать и писать документы. Третий раз слово «писать» повторять не буду — все-таки, не «Илиада». Но занудность формы чем-то определенно роднит проектную документацию с древнегреческой поэмой, особенно если речь идет о работе с государственным заказчиком.


Диаграммы — глоток творчества в этом море текста. О диаграммах и пойдет речь в данной статье. Если точнее — о PlantUML — с моей точки зрения, наиболее адекватном инструменте их создания на текущий момент.

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

Интерфейс работы с таблицей: быстро/неудобно — медленно/удобно

Website development *SQL *
Sandbox
Есть вопросы, которые, казалось бы, не могут быть не решены. Слишком часто мы с ними встречаемся в повседневной жизни. Но посмотришь внимательно — и оказывается, нет, не решены. Все делают по-разному. И не всегда хорошо. Одним из таких вопросов является взаимодействие пользовательского интерфейса работы с таблицей и системы управления базами данных (СУБД).



Требования понятны. Данные должны отображаться быстро, создавать минимальную нагрузку на СУБД и работа с ними должна быть удобна пользователю. Решения вроде тоже все есть. Но все равно даже в очень успешных проектах применены технологии, которые заставляют предположить, что разработчики решили еще раз придумать “самое лучшее” решение.

Хотелось бы рассмотреть современные подходы к решению этой задачи и подумать, есть ли наилучший вариант. И, если нет, когда что лучше использовать.
Читать дальше →
Total votes 20: ↑16 and ↓4 +12
Views 14K
Comments 32

Information

Rating
537-th
Location
Москва, Москва и Московская обл., Россия
Registered
Activity