Альтернативный способ ведения документации.

[mixyil1.1]

Как говорили в телефонном разговоре, приведу описание альтенативного способа (отличный от MS Word) ведения документации РЭА.

Мотивация: ведение документации в MS Word вызывает ряд неудобств. Мы попробовали связку Markdown → Pandoc → LaTeX: содержимое хранится в виде простых текстовых файлов, разбитых по пунктам, а итоговый PDF собирается из них одной командой. Наш наш взглят так руководство проще редактировать: правка затрагивает один небольшой файл, нет «плывущей» вёрстки (текст правится независимо от оформления), оглавление собирается автоматически. Для внесения изменений достаточно отредактировать нужный файл (текстовый файл) и выполнить сборку. Нужно запустить одну командой, технические детали скрыты в скрипте сборки (Makefile).

Шаг 1. Подготовительная часть.

• Мы преобразовали документ MC04-DSL-3U_РЭ-78_12-11-2025.docx из формата MS Word в формат Markdown rea_78.md + извлекли все картинки из документа и сложили в отдельной папке img.
• Разделили содержимое 1 большого файла rea_78.md на отдельные файлы. Для каждого пункта (2.3, 5.1 ...) и подпункта (4.2.1, 5.2.1 ...) создавали отдельный файл имя.md. Мы выделили только часть пунктов.
• Поправили содержимое файлов после конвертации (проблема - форматирование таблиц).

Итог: содержимое руководства разбито на набор текстовых фалов в формате Markdown,
все картинки лежат отдельными файлами в папке img.

Шаг 2. Техническая часть.

• Описали структуру итогового документа. Какие файлы и в каком порядке будем добавлять в документ.
• Задали команды преобразования набор файлов mardown -> итоговый документ pdf. Составили итоговый файл сборки для linux (Makefile) и windows (build.ps1).
• Описали правила форматирования для итогового документа (шрифт, отступы, оглавлениие, ...).

Итог: реализована "сборка" руководства 1 командой.

Шаг 3. Внесение изменений и генерация документа "руководство по эксплуатации".

После выполнения первых 2 шагов схема готова к использованию.

Пример работы с документацией.
Что меняем:

• Текст в описании платы (например, E1), включая ссылки на картинки.
• Набор картинок в папке img — добавить новую или заменить существующую.
• Структуру — добавить новый раздел (например, в описание платы VE-02).
• Удалить описание устаревшей платы.
• Менять пункты, разделы местами.

Как собрать и проверить:

• Выполнить make — собрать итоговый PDF. Для window нажать правую кнопку мыши и выпрать пункт запустить в powershell.
• Открыть PDF и проверить: правки на месте, картинки отображаются, оглавление обновилось.

---

Наш наш взглят такой способ хорошо подходит для ведения документации такого объема как руководство по эксплуатации и позволяет получить определенные плюсы. Однако он же сопряжен и с определенными трудностями.

Плюсы:

• текс правиться отдельно от форматирования
• автоматическая нумерация пунктов, картинок, таблиц
• можно добавить в систему контроля версий
• конвертировать в различные форматы. Например html и добавить документацию в web интерфейс управления.

Какие трудности:

• непревычно. Нужно разобраться с Markdown.
• много подготовительной работы (но нужно сделать 1 раз).
• сложности с редактированием таблиц.

Ниже прикрепляю:

• пример сгенерированого pdf файла руководства.
• ​архив с исходниками. Можно повторить сборку. Для window нужно установить дополнительное ПО MikTex, pandoc. Запустить сборку - нажать правой кнопкой на файл build.ps1 и выбрать "выполнить скрипт". В папке build аоявиться готовый pdf.